Display a popover when hovering over highlighted mentions

src/sidebar/components/MarkdownView.tsx

@@ -1,19 +1,35 @@
-import { useEffect, useMemo, useRef } from 'preact/hooks';
+import { Popover } from '@hypothesis/frontend-shared';
+import classnames from 'classnames';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'preact/hooks';
 
 import type { Mention } from '../../types/api';
+import type { InvalidUsername } from '../helpers/mentions';
 import { renderMentionTags } from '../helpers/mentions';
 import { replaceLinksWithEmbeds } from '../media-embedder';
 import { renderMathAndMarkdown } from '../render-markdown';
 import StyledText from './StyledText';
+import MentionPreviewContent from './mentions/MentionPreviewContent';
 
 export type MarkdownViewProps = {
   /** The string of markdown to display as HTML. */
   markdown: string;
   classes?: string;
   style?: Record<string, string>;
   mentions?: Mention[];
+
+  // Test seams
+  setTimeout_?: typeof setTimeout;
+  clearTimeout_?: typeof clearTimeout;
 };
 
+type PopoverContent = Mention | InvalidUsername | null;
+
 /**
  * A component which renders markdown as HTML and replaces recognized links
  * with embedded video/audio.
@@ -22,14 +38,49 @@ export default function MarkdownView({
   markdown,
   classes,
   style,
-  mentions,
+  mentions = [],
+  /* istanbul ignore next - test seam */
+  setTimeout_ = setTimeout,
+  /* istanbul ignore next - test seam */
+  clearTimeout_ = clearTimeout,
 }: MarkdownViewProps) {
   const html = useMemo(
     () => (markdown ? renderMathAndMarkdown(markdown) : ''),
     [markdown],
   );
   const content = useRef<HTMLDivElement | null>(null);
 
+  const mentionsPopoverAnchorRef = useRef<HTMLElement | null>(null);
+  const elementToMentionMap = useRef(
+    new Map<HTMLElement, Mention | InvalidUsername>(),
+  );
+  const [popoverContent, doSetPopoverContent] = useState<PopoverContent>(null);
+  /**
+   * This allows the content to be set with a small delay, so that popovers don't flickr
+   */
+  const popoverContentTimeout = useRef<ReturnType<typeof setTimeout> | null>();
+  const setPopoverContent = useCallback(
+    (content: PopoverContent) => {
+      if (popoverContentTimeout.current) {
+        clearTimeout_(popoverContentTimeout.current);
+      }
+
+      const setContent = () => {
+        doSetPopoverContent(content);
+        popoverContentTimeout.current = null;
+      };
+
+      // Set the content immediately when resetting, so that there's no delay
+      // when hiding the popover, only when showing it
+      if (content === null) {
+        setContent();
+      } else {
+        popoverContentTimeout.current = setTimeout_(setContent, 400);
+      }
+    },
+    [clearTimeout_, setTimeout_],
+  );
+
   useEffect(() => {
     replaceLinksWithEmbeds(content.current!, {
       // Make embeds the full width of the sidebar, unless the sidebar has been
@@ -40,7 +91,7 @@ export default function MarkdownView({
   }, [markdown]);
 
   useEffect(() => {
-    renderMentionTags(content.current!, mentions ?? []);
+    elementToMentionMap.current = renderMentionTags(content.current!, mentions);
   }, [mentions]);
 
   // NB: The following could be implemented by setting attribute props directly
@@ -50,14 +101,53 @@ export default function MarkdownView({
   // a review in the future.
   return (
     <div className="w-full break-anywhere cursor-text">
-      <StyledText>
+      <StyledText
+        classes={classnames(
+          // A `relative` wrapper around the `Popover` component is needed for
+          // when the native Popover API is not supported.
+          'relative',
+        )}
+      >
         <div
           className={classes}
           data-testid="markdown-text"
           ref={content}
           dangerouslySetInnerHTML={{ __html: html }}
           style={style}
+          // React types do not define `onMouseEnterCapture`, but preact does
+          // eslint-disable-next-line react/no-unknown-property
+          onMouseEnterCapture={({ target }) => {
+            const element = target as HTMLElement;
+            const mention = elementToMentionMap.current.get(element);
+
+            if (mention) {
+              setPopoverContent(mention);
+              mentionsPopoverAnchorRef.current = element;
+            }
+          }}
+          // React types do not define `onMouseLeaveCapture`, but preact does
+          // eslint-disable-next-line react/no-unknown-property
+          onMouseLeaveCapture={() => {
+            setPopoverContent(null);
+            mentionsPopoverAnchorRef.current = null;
+          }}
         />
+        <Popover
+          open={!!popoverContent}
+          onClose={() => setPopoverContent(null)}
+          anchorElementRef={mentionsPopoverAnchorRef}
+          classes="px-3 py-2"
+        >
+          {typeof popoverContent === 'string' && (
+            <>
+              No user with username{' '}
+              <span className="font-bold">{popoverContent}</span> exists
+            </>
+          )}
+          {popoverContent !== null && typeof popoverContent === 'object' && (
+            <MentionPreviewContent mention={popoverContent} />
+          )}
+        </Popover>
       </StyledText>
     </div>
   );

src/sidebar/components/mentions/MentionPreviewContent.tsx

@@ -0,0 +1,21 @@
+import type { Mention } from '../../../types/api';
+
+export type MentionPreviewContent = {
+  mention: Mention;
+};
+
+/**
+ * Information to display on a Popover when hovering over a processed mention
+ */
+export default function MentionPreviewContent({
+  mention,
+}: MentionPreviewContent) {
+  return (
+    <div className="flex flex-col gap-y-1.5">
+      <div className="text-md font-bold">@{mention.username}</div>
+      {mention.display_name && (
+        <div className="text-color-text-light">{mention.display_name}</div>
+      )}
+    </div>
+  );
+}