box-annotations 5.2.1-beta.7 → 5.3.0

package/dist/annotations.js.LICENSE.txt

@@ -39,7 +39,7 @@ object-assign
  * LICENSE file in the root directory of this source tree.
  */
 
-/** @license React v16.12.0
+/** @license React v16.13.1
  * react-is.production.min.js
  *
  * Copyright (c) Facebook, Inc. and its affiliates.

package/index.js

@@ -1,4 +1,4 @@
 import './dist/annotations.css';
-import './dist/annotations.js';
+import BoxAnnotations from './dist/annotations.js';
 
 export default BoxAnnotations;

package/package.json

@@ -1,9 +1,14 @@
 {
     "name": "box-annotations",
-    "version": "5.2.1-beta.7",
+    "version": "5.3.0",
     "description": "Box Annotations",
     "author": "Box (https://www.box.com/)",
     "license": "SEE LICENSE IN LICENSE",
+    "sideEffects": [
+        "./dist/annotations.js",
+        "**/*.css",
+        "**/*.scss"
+    ],
     "repository": {
         "type": "git",
         "url": "git@github.com:box/box-annotations.git"
@@ -12,7 +17,7 @@
         "registry": "https://registry.npmjs.org/"
     },
     "engines": {
-        "node": ">=18.x",
+        "node": ">=20.x",
         "yarn": ">=1.10.x"
     },
     "devDependencies": {
@@ -27,14 +32,17 @@
         "@babel/preset-env": "^7.25.9",
         "@babel/preset-react": "^7.25.9",
         "@babel/preset-typescript": "^7.25.9",
+        "@box/blueprint-web": "^16.12.0",
+        "@box/blueprint-web-assets": "^5.5.12",
+        "@box/collaboration-popover": "^2.1.32",
+        "@box/combobox-with-api": "^1.42.22",
         "@box/frontend": "^10.0.0",
-        "@box/blueprint-web": "^14.12.2",
-        "@box/blueprint-web-assets": "^4.114.3",
-        "@box/collaboration-popover": "^1.60.2",
+        "@box/item-icon": "^3.2.0",
         "@box/languages": "^1.1.0",
-        "@box/readable-time": "^1.39.52",
-        "@box/threaded-annotations": "^1.80.0",
-        "@box/user-selector": "^1.74.52",
+        "@box/readable-time": "^2.1.32",
+        "@box/threaded-annotations": "^4.11.0",
+        "@box/types": "^2.1.8",
+        "@box/user-selector": "^2.1.35",
         "@cfaester/enzyme-adapter-react-18": "^0.8.0",
         "@commitlint/cli": "^8.3.5",
         "@commitlint/config-conventional": "^8.2.0",
@@ -48,7 +56,7 @@
         "@types/classnames": "^2.2.10",
         "@types/draft-js": "^0.10.40",
         "@types/enzyme": "^3.10.5",
-        "@types/jest": "^24.9.0",
+        "@types/jest": "^29.5.14",
         "@types/lodash": "^4.14.150",
         "@types/react": "18.3.12",
         "@types/react-dom": "18.3.1",
@@ -59,7 +67,7 @@
         "autoprefixer": "^10.4.19",
         "axios": "^0.24.0",
         "babel-eslint": "^10.1.0",
-        "babel-jest": "^24.9.0",
+        "babel-jest": "^29.7.0",
         "babel-loader": "^9.2.1",
         "babel-plugin-istanbul": "^6.0.0",
         "babel-plugin-react-intl": "^7.5.1",
@@ -73,7 +81,7 @@
         "core-js": "^3.38.1",
         "css-loader": "^7.1.2",
         "css-minimizer-webpack-plugin": "^7.0.4",
-        "cypress": "^4.4.1",
+        "cypress": "^15.20.1",
         "draft-js": "0.10.5",
         "enzyme": "^3.11.0",
         "enzyme-to-json": "^3.4.4",
@@ -93,9 +101,9 @@
         "eslint-plugin-react-hooks": "^4.6.0",
         "formik": "^2.1.4",
         "husky": "^3.1.0",
-        "jest": "^24.9.0",
-        "jest-canvas-mock": "^2.4.0",
-        "jest-environment-jsdom-sixteen": "^1.0.3",
+        "jest": "^29.7.0",
+        "jest-canvas-mock": "^2.5.2",
+        "jest-environment-jsdom": "^29.7.0",
         "lint-staged": "^9.5.0",
         "lodash": "^4.17.15",
         "mini-css-extract-plugin": "^2.10.1",
@@ -121,19 +129,22 @@
         "tabbable": "^1.1.3",
         "typescript": "4.9.5",
         "uuid": "^8.3.1",
-        "wait-on": "^4.0.2",
+        "wait-on": "^9.0.5",
         "webpack": "^5.105.4",
         "webpack-cli": "^5.1.4",
         "webpack-dev-server": "^5.2.3",
         "worker-farm": "^1.7.0"
     },
     "peerDependencies": {
-        "@box/blueprint-web": "^14.12.2",
-        "@box/blueprint-web-assets": "^4.114.3",
-        "@box/collaboration-popover": "^1.60.2",
-        "@box/readable-time": "^1.39.52",
-        "@box/threaded-annotations": "^1.80.0",
-        "@box/user-selector": "^1.74.52"
+        "@box/blueprint-web": "^16.12.0",
+        "@box/blueprint-web-assets": "^5.5.12",
+        "@box/collaboration-popover": "^2.1.32",
+        "@box/combobox-with-api": "^1.42.22",
+        "@box/item-icon": "^3.2.0",
+        "@box/readable-time": "^2.1.32",
+        "@box/threaded-annotations": "^4.11.0",
+        "@box/types": "^2.1.8",
+        "@box/user-selector": "^2.1.35"
     },
     "scripts": {
         "build": "yarn setup && yarn build:prod:dist",
@@ -143,7 +154,7 @@
         "clean": "rm -rf dist reports/* i18n/json i18n/*.js",
         "cy:open": "yarn cy:wait; yarn cypress open",
         "cy:run": "yarn cy:wait; yarn cypress run --spec test/integration/**/*.test.js",
-        "cy:wait": "wait-on http-get://localhost:8001",
+        "cy:wait": "wait-on http-get://127.0.0.1:8001",
         "lint": "npm-run-all lint:*",
         "lint:js": "eslint .",
         "lint:scss": "stylelint \"src/**/*.scss\" --syntax scss",

package/src/@types/api.ts

@@ -10,5 +10,6 @@ export interface Permissions {
 }
 
 export type TokenLiteral = null | undefined | string | { read: string; write?: string };
-export type TokenResolver = () => TokenLiteral | Promise<TokenLiteral>;
-export type Token = TokenLiteral | TokenResolver;
+export type TokenMap = { [typedFileId: string]: TokenLiteral };
+export type TokenResolver = (typedFileId?: string) => TokenLiteral | TokenMap | Promise<TokenLiteral | TokenMap>;
+export type Token = TokenLiteral | TokenMap | TokenResolver;

package/src/@types/events.ts

@@ -1,19 +1,36 @@
 enum Event {
-    ACTIVE_CHANGE = 'annotations_active_change',
+    // Inbound: emitted by the host; box-annotations listens.
     ACTIVE_SET = 'annotations_active_set',
-    CREATOR_STAGED_CHANGE = 'creator_staged_change',
-    CREATOR_STATUS_CHANGE = 'creator_status_change',
+    ANNOTATION_REMOVE = 'annotations_remove',
+    BOUNDING_BOX_HIGHLIGHTS_SET = 'bounding_box_highlights_set',
+    BOUNDING_BOX_HIGHLIGHT_SELECT = 'bounding_box_highlight_select',
+    COLOR_SET = 'annotations_color_set',
+    VIEW_MODE_SET = 'view_mode_set',
+    VISIBLE_SET = 'annotations_visible_set',
+
+    // Outbound: emitted by box-annotations; the host listens.
+    ACTIVE_CHANGE = 'annotations_active_change',
     ANNOTATION_CREATE = 'annotations_create',
+    ANNOTATION_DELETE = 'annotations_delete',
     ANNOTATION_FETCH_ERROR = 'annotations_fetch_error',
-    ANNOTATION_REMOVE = 'annotations_remove',
+    ANNOTATION_REPLY_CREATE = 'annotations_reply_create',
+    ANNOTATION_REPLY_DELETE = 'annotations_reply_delete',
+    ANNOTATION_REPLY_UPDATE = 'annotations_reply_update',
+    ANNOTATION_UPDATE = 'annotations_update',
     ANNOTATIONS_INITIALIZED = 'annotations_initialized',
     ANNOTATIONS_MODE_CHANGE = 'annotations_mode_change',
-    COLOR_SET = 'annotations_color_set',
-    BOUNDING_BOX_HIGHLIGHTS_SET = 'bounding_box_highlights_set',
+    CREATOR_STAGED_CHANGE = 'creator_staged_change',
+    CREATOR_STATUS_CHANGE = 'creator_status_change',
+
+    // Internal: box-annotations emits and listens to itself (redux state change → DOM side effect).
     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',
+}
+
+enum SidebarEvent {
+    SIDEBAR_ANNOTATION_UPDATE = 'sidebar.annotations_update',
+    SIDEBAR_REPLY_CREATE = 'sidebar.annotations_reply_create',
+    SIDEBAR_REPLY_DELETE = 'sidebar.annotations_reply_delete',
+    SIDEBAR_REPLY_UPDATE = 'sidebar.annotations_reply_update',
 }
 
 // Existing legacy events, don't rename
@@ -23,4 +40,4 @@ enum LegacyEvent {
     SCALE = 'scaleannotations',
 }
 
-export { Event, LegacyEvent };
+export { Event, LegacyEvent, SidebarEvent };

package/src/@types/global.ts

@@ -1,12 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-namespace */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-declare namespace NodeJS {
-    interface Global {
-        window: any;
-        BoxAnnotations: any;
-    }
-}
-
 declare module 'box-annotations-locale-data';
 declare module 'box-elements-messages';
 declare module 'box-ui-elements/es/*'; // TODO: Figure out why types don't register properly

package/src/@types/model.ts

@@ -86,15 +86,24 @@ export interface Rect extends Position {
     width: number;
 }
 
+export interface ReplyPermissions {
+    can_delete?: boolean;
+    can_edit?: boolean;
+    can_reply?: boolean;
+    can_resolve?: boolean;
+}
+
 export interface Reply {
     created_at: string;
     created_by: User;
     id: string;
     message: string;
+    modified_at?: string;
     parent: {
         id: string;
         type: string;
     };
+    permissions?: ReplyPermissions;
     type: 'reply';
 }
 

package/src/BoxAnnotations.ts

@@ -16,9 +16,11 @@ type Annotator = {
 type AnnotationsOptions = {
     features: Features;
     intl: IntlOptions;
+    onCopyLink?: (params: { annotationId: string; fileVersionId: string }) => void;
 };
 
 export type Features = {
+    isRichTextEnabled?: boolean;
     isThreadedAnnotation?: boolean;
     [key: string]: boolean | undefined;
 };
@@ -43,6 +45,8 @@ type ViewerOption = {
 
 type ViewerOptions = Record<string, ViewerOption>;
 
+type GlobalWithBoxAnnotations = typeof globalThis & { BoxAnnotations: typeof BoxAnnotations };
+
 /**
  * NAME: The name of the annotator.
  * CONSTRUCTOR: Constructor for the annotator.
@@ -145,5 +149,5 @@ class BoxAnnotations {
     }
 }
 
-global.BoxAnnotations = BoxAnnotations;
+(globalThis as GlobalWithBoxAnnotations).BoxAnnotations = BoxAnnotations;
 export default BoxAnnotations;

package/src/adapters/threadedAnnotationsAdapters.ts

@@ -1,4 +1,5 @@
 import type { DocumentNodeV2, MentionNodeV2, ParagraphNodeV2, TextMessageTypeV2, TextNodeV2 } from '@box/threaded-annotations';
+import { parseMessageMarkdown } from '@box/threaded-annotations';
 
 import type { Annotation, Collaborator, Reply, UserMini } from '../@types';
 
@@ -69,10 +70,27 @@ export const deserializeMentionMarkup = (text: string): DocumentNodeV2 => {
     return { type: 'doc', content };
 };
 
+const toDocumentNode = (text: string, isRichTextEnabled = false): DocumentNodeV2 =>
+    isRichTextEnabled ? (parseMessageMarkdown(text) as DocumentNodeV2) : deserializeMentionMarkup(text);
+
+/**
+ * Returns the edit timestamp consumers use to render an edited indicator.
+ * Compares parsed instants, not raw strings, so equivalent ISO formats
+ * (Z vs +00:00, fractional precision) are treated as unedited.
+ */
+const toUpdatedAt = (createdAt: string, modifiedAt: string | undefined): number | undefined => {
+    if (!modifiedAt) return undefined;
+    const modifiedMs = new Date(modifiedAt).getTime();
+    if (Number.isNaN(modifiedMs)) return undefined;
+    const createdMs = new Date(createdAt).getTime();
+    if (modifiedMs === createdMs) return undefined;
+    return modifiedMs;
+};
+
 /**
  * Converts a box-annotations Reply to a threaded-annotations TextMessageType.
  */
-export const replyToTextMessage = (reply: Reply): TextMessageTypeV2 => ({
+export const replyToTextMessage = (reply: Reply, isRichTextEnabled = false): TextMessageTypeV2 => ({
     author: {
         email: reply.created_by?.login ?? '',
         id: parseInt(reply.created_by?.id ?? '0', 10),
@@ -80,55 +98,50 @@ export const replyToTextMessage = (reply: Reply): TextMessageTypeV2 => ({
     },
     createdAt: new Date(reply.created_at).getTime(),
     id: reply.id,
-    message: deserializeMentionMarkup(reply.message),
+    message: toDocumentNode(reply.message, isRichTextEnabled),
     permissions: {
-        canDelete: false,
-        canEdit: false,
-        canReply: true,
-        canResolve: false,
+        canDelete: reply.permissions?.can_delete ?? false,
+        canEdit: reply.permissions?.can_edit ?? false,
+        canReply: reply.permissions?.can_reply ?? false,
+        canResolve: reply.permissions?.can_resolve ?? false,
     },
+    updatedAt: toUpdatedAt(reply.created_at, reply.modified_at),
 });
 
-/**
- * Converts an Annotation's description (root message) to a TextMessageType.
- * The root message gets resolve permission from the annotation's permissions.
- * Falls back to annotation-level fields when the description object is sparse
- * (the list endpoint returns description with only { message }).
- */
-const descriptionToTextMessage = (
-    annotation: Annotation,
-    reply: Reply,
-): TextMessageTypeV2 => ({
+// The root message shares the annotation's author and permissions; description
+// comes back sparse ({ message } only) from the list endpoint.
+const descriptionToTextMessage = (annotation: Annotation, isRichTextEnabled = false): TextMessageTypeV2 => ({
     author: {
-        email: (reply.created_by ?? annotation.created_by)?.login ?? '',
-        id: parseInt((reply.created_by ?? annotation.created_by)?.id ?? '0', 10),
-        name: (reply.created_by ?? annotation.created_by)?.name ?? '',
+        email: annotation.created_by?.login ?? '',
+        id: parseInt(annotation.created_by?.id ?? '0', 10),
+        name: annotation.created_by?.name ?? '',
     },
-    createdAt: new Date(reply.created_at ?? annotation.created_at).getTime(),
-    id: reply.id ?? annotation.id,
-    message: deserializeMentionMarkup(reply.message),
+    createdAt: new Date(annotation.created_at).getTime(),
+    id: annotation.id,
+    message: toDocumentNode(annotation.description?.message ?? '', isRichTextEnabled),
     permissions: {
         canDelete: annotation.permissions?.can_delete ?? false,
         canEdit: annotation.permissions?.can_edit ?? false,
-        canReply: true,
+        canReply: annotation.permissions?.can_reply ?? false,
         canResolve: annotation.permissions?.can_resolve ?? false,
     },
+    updatedAt: toUpdatedAt(annotation.created_at, annotation.modified_at),
 });
 
 /**
  * Maps a full Annotation (description + replies) to an array of TextMessageType
  * suitable for ThreadedAnnotationsV2.
  */
-export const annotationToMessages = (annotation: Annotation): TextMessageTypeV2[] => {
+export const annotationToMessages = (annotation: Annotation, isRichTextEnabled = false): TextMessageTypeV2[] => {
     const messages: TextMessageTypeV2[] = [];
 
     if (annotation.description) {
-        messages.push(descriptionToTextMessage(annotation, annotation.description));
+        messages.push(descriptionToTextMessage(annotation, isRichTextEnabled));
     }
 
     if (annotation.replies) {
         annotation.replies.forEach(reply => {
-            messages.push(replyToTextMessage(reply));
+            messages.push(replyToTextMessage(reply, isRichTextEnabled));
         });
     }
 

package/src/api/APIFactory.ts

@@ -1,7 +1,8 @@
 import Annotations from 'box-ui-elements/es/api/Annotations';
 import FileCollaborators from 'box-ui-elements/es/api/FileCollaborators';
+import ThreadedComments from 'box-ui-elements/es/api/ThreadedComments';
 import { DEFAULT_HOSTNAME_API } from 'box-ui-elements/es/constants';
-import { AnnotationsAPI, CollaboratorsAPI, APIOptions } from './types';
+import { AnnotationsAPI, CollaboratorsAPI, APIOptions, ThreadedCommentsAPI } from './types';
 
 export default class APIFactory {
     options: APIOptions;
@@ -21,4 +22,8 @@ export default class APIFactory {
     getCollaboratorsAPI(): CollaboratorsAPI {
         return new FileCollaborators(this.options);
     }
+
+    getThreadedCommentsAPI(): ThreadedCommentsAPI {
+        return new ThreadedComments(this.options);
+    }
 }

package/src/api/types.ts

@@ -1,4 +1,4 @@
-import { Annotation, Collaborator, NewAnnotation, Permissions, Reply, Token } from '../@types';
+import { Annotation, Collaborator, NewAnnotation, Permissions, Reply, ReplyPermissions, Token } from '../@types';
 
 export type APICollection<R> = {
     entries: R[];
@@ -73,6 +73,28 @@ export interface AnnotationsAPI {
     destroy(): void;
 }
 
+export interface ThreadedCommentsAPI {
+    deleteComment(args: {
+        commentId: string;
+        errorCallback: (error: APIError) => void;
+        fileId: string | null;
+        permissions: ReplyPermissions;
+        successCallback: () => void;
+    }): void;
+
+    updateComment(args: {
+        commentId: string;
+        errorCallback: (error: APIError) => void;
+        fileId: string | null;
+        message?: string;
+        permissions: ReplyPermissions;
+        status?: string;
+        successCallback: (reply: Reply) => void;
+    }): void;
+
+    destroy(): void;
+}
+
 export interface CollaboratorsAPI {
     getFileCollaborators(
         fileId: string | null,

package/src/common/AnnotationCallbacksContext.ts

@@ -0,0 +1,7 @@
+import { createContext } from 'react';
+
+export type AnnotationCallbacks = {
+    onCopyLink?: (params: { annotationId: string; fileVersionId: string }) => void;
+};
+
+export default createContext<AnnotationCallbacks>({});

package/src/common/BaseAnnotator.scss

@@ -7,7 +7,8 @@
     @import '~box-ui-elements/es/styles/common/buttons';
 
     &.is-hidden {
-        .ba-Layer {
+        .ba-Layer,
+        .ba-PopupPortal {
             display: none;
         }
     }
@@ -27,3 +28,15 @@
 .ba-Layer--popup {
     z-index: 4;
 }
+
+.ba-PopupPortal {
+    position: relative;
+    z-index: 10;
+    pointer-events: none;
+
+    .ba-Popup,
+    .ba-PopupV2 {
+        z-index: 150;
+        pointer-events: auto;
+    }
+}

package/src/common/BaseAnnotator.ts

@@ -6,7 +6,7 @@ import DeselectManager from './DeselectManager';
 import EventEmitter from './EventEmitter';
 import i18n from '../utils/i18n';
 import messages from '../messages';
-import { Event, IntlOptions, LegacyEvent, Permissions } from '../@types';
+import { Event, IntlOptions, LegacyEvent, Permissions, SidebarEvent, Token } from '../@types';
 import { BoundingBox, getBoundingBoxHighlights } from '../store/boundingBoxHighlights';
 import { ViewMode } from '../store/options/types';
 import { Features } from '../BoxAnnotations';
@@ -44,11 +44,13 @@ export type Options = {
     initialViewMode?: ViewMode;
     intl: IntlOptions;
     locale?: string;
-    token: string;
+    onCopyLink?: (params: { annotationId: string; fileVersionId: string }) => void;
+    token: Token;
 };
 
 export const CSS_CONTAINER_CLASS = 'ba';
 export const CSS_LOADED_CLASS = 'ba-annotations-loaded';
+export const CSS_POPUP_PORTAL_CLASS = 'ba-PopupPortal';
 export const ANNOTATION_CLASSES: { [M in store.Mode]?: string } = {
     [store.Mode.HIGHLIGHT]: 'ba-is-create--highlight',
     [store.Mode.REGION]: 'ba-is-create--region',
@@ -59,6 +61,8 @@ export default class BaseAnnotator extends EventEmitter {
 
     containerEl?: HTMLElement | null;
 
+    popupPortalEl?: HTMLElement | null;
+
     container: Container;
 
     deselectManager: DeselectManager | null = null;
@@ -67,6 +71,8 @@ export default class BaseAnnotator extends EventEmitter {
 
     intl: IntlShape;
 
+    onCopyLink?: (params: { annotationId: string; fileVersionId: string }) => void;
+
     store: store.AppStore;
 
     constructor({
@@ -79,6 +85,7 @@ export default class BaseAnnotator extends EventEmitter {
         initialMode,
         initialViewMode = 'annotations',
         intl,
+        onCopyLink,
         token,
     }: Options) {
         super();
@@ -108,6 +115,7 @@ export default class BaseAnnotator extends EventEmitter {
         this.container = container;
         this.features = features;
         this.intl = i18n.createIntlProvider(intl);
+        this.onCopyLink = onCopyLink;
         this.store = store.createStore(initialState, {
             api: new API({ apiHost, token }),
         });
@@ -123,6 +131,11 @@ export default class BaseAnnotator extends EventEmitter {
         this.addListener(Event.BOUNDING_BOX_HIGHLIGHT_SELECT, this.handleSelectBoundingBoxHighlight);
         this.addListener(Event.VIEW_MODE_SET, this.handleSetViewMode);
 
+        this.addListener(SidebarEvent.SIDEBAR_ANNOTATION_UPDATE, this.handleSidebarAnnotationUpdate);
+        this.addListener(SidebarEvent.SIDEBAR_REPLY_CREATE, this.handleSidebarReplyCreate);
+        this.addListener(SidebarEvent.SIDEBAR_REPLY_UPDATE, this.handleSidebarReplyUpdate);
+        this.addListener(SidebarEvent.SIDEBAR_REPLY_DELETE, this.handleSidebarReplyDelete);
+
         // Load any required data at startup
         this.hydrate();
     }
@@ -132,6 +145,11 @@ export default class BaseAnnotator extends EventEmitter {
             this.containerEl.classList.remove(CSS_CONTAINER_CLASS);
         }
 
+        if (this.popupPortalEl) {
+            this.popupPortalEl.remove();
+            this.popupPortalEl = null;
+        }
+
         if (this.annotatedEl) {
             this.annotatedEl.classList.remove(CSS_LOADED_CLASS);
         }
@@ -151,6 +169,10 @@ export default class BaseAnnotator extends EventEmitter {
         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);
+        this.removeListener(SidebarEvent.SIDEBAR_ANNOTATION_UPDATE, this.handleSidebarAnnotationUpdate);
+        this.removeListener(SidebarEvent.SIDEBAR_REPLY_CREATE, this.handleSidebarReplyCreate);
+        this.removeListener(SidebarEvent.SIDEBAR_REPLY_UPDATE, this.handleSidebarReplyUpdate);
+        this.removeListener(SidebarEvent.SIDEBAR_REPLY_DELETE, this.handleSidebarReplyDelete);
     }
 
     public init(scale = 1, rotation = 0): void {
@@ -166,6 +188,12 @@ export default class BaseAnnotator extends EventEmitter {
         this.annotatedEl.classList.add(CSS_LOADED_CLASS);
         this.containerEl.classList.add(CSS_CONTAINER_CLASS);
 
+        if (!this.popupPortalEl) {
+            this.popupPortalEl = this.containerEl.ownerDocument.createElement('div');
+            this.popupPortalEl.classList.add(CSS_POPUP_PORTAL_CLASS);
+            this.containerEl.appendChild(this.popupPortalEl);
+        }
+
         // Defer to the child class to render annotations
         this.render();
 
@@ -338,6 +366,22 @@ export default class BaseAnnotator extends EventEmitter {
         this.setViewMode(viewMode);
     };
 
+    protected handleSidebarAnnotationUpdate = (annotation: store.SidebarAnnotationUpdatePayload): void => {
+        this.store.dispatch(store.applySidebarAnnotationUpdateAction(annotation));
+    };
+
+    protected handleSidebarReplyCreate = (payload: store.SidebarReplyMutationPayload): void => {
+        this.store.dispatch(store.applySidebarReplyCreateAction(payload));
+    };
+
+    protected handleSidebarReplyUpdate = (payload: store.SidebarReplyMutationPayload): void => {
+        this.store.dispatch(store.applySidebarReplyUpdateAction(payload));
+    };
+
+    protected handleSidebarReplyDelete = ({ annotationId, id }: { annotationId: string; id: string }): void => {
+        this.store.dispatch(store.applySidebarReplyDeleteAction({ annotationId, replyId: id }));
+    };
+
     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/common/BaseManager.ts

@@ -1,6 +1,7 @@
 import * as ReactDOM from 'react-dom/client';
 import { IntlShape } from 'react-intl';
 import { Store } from 'redux';
+import { AnnotationCallbacks } from './AnnotationCallbacksContext';
 import { applyResinTags } from '../utils/resin';
 import { TARGET_TYPE } from '../constants';
 
@@ -14,6 +15,7 @@ export type Options = {
 };
 
 export type Props = {
+    callbacks?: AnnotationCallbacks;
     intl: IntlShape;
     store: Store;
 };

package/src/common/DeselectListener.tsx

@@ -6,7 +6,9 @@ export default function DeselectListener(): null {
     const dispatch = useDispatch();
 
     React.useEffect(() => {
-        const handleMouseDown = (): void => {
+        const handleMouseDown = (event: MouseEvent): void => {
+            // Popup is portaled outside .ba-Layer; native mousedown still bubbles here.
+            if ((event.target as Element | null)?.closest?.('.ba-PopupV2, .ba-Popup')) return;
             dispatch(setActiveAnnotationIdAction(null));
         };
 

package/src/common/withProviders.tsx

@@ -2,8 +2,10 @@ import * as React from 'react';
 import { IntlShape, RawIntlProvider } from 'react-intl';
 import { Provider as StoreProvider } from 'react-redux';
 import { Store } from 'redux';
+import AnnotationCallbacksContext, { AnnotationCallbacks } from './AnnotationCallbacksContext';
 
 type WrapperProps = {
+    callbacks?: AnnotationCallbacks;
     intl: IntlShape;
     store: Store;
 };
@@ -11,11 +13,13 @@ type WrapperProps = {
 type WrapperReturn<P> = React.FC<P & WrapperProps>;
 
 export default function withProviders<P extends object>(WrappedComponent: React.ComponentType<P>): WrapperReturn<P> {
-    return function RootProvider({ intl, store, ...rest }: P & WrapperProps): JSX.Element {
+    return function RootProvider({ callbacks, intl, store, ...rest }: P & WrapperProps): JSX.Element {
         return (
             <RawIntlProvider value={intl}>
                 <StoreProvider store={store}>
-                    <WrappedComponent {...(rest as P)} />
+                    <AnnotationCallbacksContext.Provider value={callbacks ?? {}}>
+                        <WrappedComponent {...(rest as P)} />
+                    </AnnotationCallbacksContext.Provider>
                 </StoreProvider>
             </RawIntlProvider>
         );