hypothesis · acelaya · Mar 14, 2025 · Mar 13, 2025
diff --git a/src/sidebar/components/Annotation/AnnotationEditor.tsx b/src/sidebar/components/Annotation/AnnotationEditor.tsx
@@ -3,12 +3,14 @@ import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
 import type { Annotation } from '../../../types/api';
 import type { SidebarSettings } from '../../../types/config';
 import { serviceConfig } from '../../config/service-config';
+import { isThirdPartyUser } from '../../helpers/account-id';
 import {
   annotationRole,
   isReply,
   isSaved,
 } from '../../helpers/annotation-metadata';
 import { combineUsersForMentions } from '../../helpers/mention-suggestions';
+import type { MentionMode } from '../../helpers/mentions';
 import { applyTheme } from '../../helpers/theme';
 import { withServices } from '../../service-context';
 import type { AnnotationsService } from '../../services/annotations';
@@ -176,6 +178,15 @@ function AnnotationEditor({
 
   const textStyle = applyTheme(['annotationFontFamily'], settings);
 
+  const defaultAuthority = store.defaultAuthority();
+  const mentionMode = useMemo(
+    (): MentionMode =>
+      isThirdPartyUser(annotation.user, defaultAuthority)
+        ? 'display-name'
+        : 'username',
+    [annotation.user, defaultAuthority],
+  );
+
   const mentionsEnabled = store.isFeatureEnabled('at_mentions');
   const usersWhoAnnotated = store.usersWhoAnnotated();
   const focusedGroupMembers = store.getFocusedGroupMembers();
@@ -207,6 +218,7 @@ function AnnotationEditor({
         usersForMentions={usersForMentions}
         showHelpLink={showHelpLink}
         mentions={annotation.mentions}
+        mentionMode={mentionMode}
       />
       <TagEditor
         onAddTag={onAddTag}

diff --git a/src/sidebar/components/Annotation/test/AnnotationEditor-test.js b/src/sidebar/components/Annotation/test/AnnotationEditor-test.js
@@ -70,6 +70,7 @@ describe('AnnotationEditor', () => {
       isFeatureEnabled: sinon.stub().returns(false),
       usersWhoAnnotated: sinon.stub().returns([]),
       getFocusedGroupMembers: sinon.stub().returns({ status: 'not-loaded' }),
+      defaultAuthority: sinon.stub().returns(''),
     };
 
     $imports.$mock(mockImportedComponents());
@@ -449,6 +450,33 @@ describe('AnnotationEditor', () => {
     });
   });
 
+  [
+    {
+      defaultAuthority: 'example.com',
+      expectedMentionMode: 'username',
+    },
+    {
+      defaultAuthority: 'foo.com',
+      expectedMentionMode: 'display-name',
+    },
+  ].forEach(({ defaultAuthority, expectedMentionMode }) => {
+    it('sets expected mention mode based on annotation author', () => {
+      fakeStore.defaultAuthority.returns(defaultAuthority);
+
+      const wrapper = createComponent({
+        annotation: {
+          ...fixtures.defaultAnnotation(),
+          user: 'acct:[email protected]',
+        },
+      });
+
+      assert.equal(
+        wrapper.find('MarkdownEditor').prop('mentionMode'),
+        expectedMentionMode,
+      );
+    });
+  });
+
   it(
     'should pass a11y checks',
     checkAccessibility([

diff --git a/src/sidebar/components/MarkdownEditor.tsx b/src/sidebar/components/MarkdownEditor.tsx
@@ -35,9 +35,11 @@ import type {
   UsersForMentions,
 } from '../helpers/mention-suggestions';
 import { usersMatchingMention } from '../helpers/mention-suggestions';
+import type { MentionMode } from '../helpers/mentions';
 import {
   getContainingMentionOffsets,
   termBeforePosition,
+  toPlainTextMention,
   unwrapMentions,
 } from '../helpers/mentions';
 import {
@@ -204,6 +206,7 @@ type TextAreaProps = {
   mentionsEnabled: boolean;
   usersForMentions: UsersForMentions;
   onEditText: (text: string) => void;
+  mentionMode: MentionMode;
 };
 
 function TextArea({
@@ -213,6 +216,7 @@ function TextArea({
   usersForMentions,
   onEditText,
   onKeyDown,
+  mentionMode,
   ...restProps
 }: TextAreaProps & JSX.TextareaHTMLAttributes) {
   const [popoverOpen, setPopoverOpen] = useState(false);
@@ -261,7 +265,7 @@ function TextArea({
         textarea.selectionStart,
       );
       const beforeMention = value.slice(0, start);
-      const beforeCaret = `${beforeMention}@${suggestion.username} `;
+      const beforeCaret = `${beforeMention}${toPlainTextMention(suggestion, mentionMode)} `;
       const afterMention = value.slice(end);
 
       // Set textarea value directly, set new caret position and keep it focused.
@@ -277,7 +281,7 @@ function TextArea({
       setPopoverOpen(false);
       setHighlightedSuggestion(0);
     },
-    [onEditText, textareaRef],
+    [mentionMode, onEditText, textareaRef],
   );
 
   const usersListboxId = useId();
@@ -376,6 +380,7 @@ function TextArea({
           highlightedSuggestion={highlightedSuggestion}
           onSelectUser={insertMention}
           usersListboxId={usersListboxId}
+          mentionMode={mentionMode}
         />
       )}
     </div>
@@ -547,6 +552,7 @@ export type MarkdownEditorProps = {
 
   /** List of mentions extracted from the annotation text. */
   mentions?: Mention[];
+  mentionMode: MentionMode;
 };
 
 /**
@@ -561,6 +567,7 @@ export default function MarkdownEditor({
   showHelpLink = true,
   usersForMentions,
   mentions,
+  mentionMode,
 }: MarkdownEditorProps) {
   // Whether the preview mode is currently active.
   const [preview, setPreview] = useState(false);
@@ -634,6 +641,7 @@ export default function MarkdownEditor({
           style={textStyle}
           mentionsEnabled={mentionsEnabled}
           usersForMentions={usersForMentions}
+          mentionMode={mentionMode}
         />
       )}
     </div>

diff --git a/src/sidebar/components/MentionSuggestionsPopover.tsx b/src/sidebar/components/MentionSuggestionsPopover.tsx
@@ -2,11 +2,63 @@ import { Popover } from '@hypothesis/frontend-shared';
 import type { PopoverProps } from '@hypothesis/frontend-shared/lib/components/feedback/Popover';
 import classnames from 'classnames';
 
-export type UserItem = {
-  username: string;
-  displayName: string | null;
+import type { UserItem } from '../helpers/mention-suggestions';
+import type { MentionMode } from '../helpers/mentions';
+
+type SuggestionItemProps = {
+  user: UserItem;
+  usersListboxId: string;
+  highlighted: boolean;
+  mentionMode: MentionMode;
+  onSelectUser: (user: UserItem) => void;
 };
 
+function SuggestionItem({
+  user,
+  usersListboxId,
+  highlighted,
+  mentionMode,
+  onSelectUser,
+}: SuggestionItemProps) {
+  const showUsername = mentionMode === 'username';
+
+  return (
+    // These options are indirectly handled via keyboard event
+    // handlers in the textarea, hence, we don't want to add keyboard
+    // event handlers here, but we want to handle click events.
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events
+    <li
+      key={user.username}
+      id={`${usersListboxId}-${user.username}`}
+      className={classnames(
+        'flex justify-between items-center gap-x-2',
+        'rounded p-2 hover:bg-grey-2',
+        // Adjust line height relative to the font size. This avoids
+        // vertically cropped usernames due to the use of `truncate`.
+        'leading-tight',
+        {
+          'bg-grey-2': highlighted,
+        },
+      )}
+      onClick={e => {
+        e.stopPropagation();
+        onSelectUser(user);
+      }}
+      role="option"
+      aria-selected={highlighted}
+    >
+      {showUsername && (
+        <span className="truncate" data-testid={`username-${user.username}`}>
+          {user.username}
+        </span>
+      )}
+      <span className={classnames({ 'text-color-text-light': showUsername })}>
+        {user.displayName}
+      </span>
+    </li>
+  );
+}
+
 export type MentionSuggestionsPopoverProps = Pick<
   PopoverProps,
   'open' | 'onClose' | 'anchorElementRef'
@@ -21,6 +73,8 @@ export type MentionSuggestionsPopoverProps = Pick<
   onSelectUser: (selectedSuggestion: UserItem) => void;
   /** Element ID for the user suggestions listbox */
   usersListboxId: string;
+  /** Determines what information to display in suggestions */
+  mentionMode: MentionMode;
 };
 
 /**
@@ -32,6 +86,7 @@ export default function MentionSuggestionsPopover({
   onSelectUser,
   highlightedSuggestion,
   usersListboxId,
+  mentionMode,
   ...popoverProps
 }: MentionSuggestionsPopoverProps) {
   return (
@@ -52,33 +107,14 @@ export default function MentionSuggestionsPopover({
         ) : (
           <>
             {users.map((u, index) => (
-              // These options are indirectly handled via keyboard event
-              // handlers in the textarea, hence, we don't want to add keyboard
-              // event handlers here, but we want to handle click events.
-              // eslint-disable-next-line jsx-a11y/click-events-have-key-events
-              <li
+              <SuggestionItem
                 key={u.username}
-                id={`${usersListboxId}-${u.username}`}
-                className={classnames(
-                  'flex justify-between items-center gap-x-2',
-                  'rounded p-2 hover:bg-grey-2',
-                  // Adjust line height relative to the font size. This avoids
-                  // vertically cropped usernames due to the use of `truncate`.
-                  'leading-tight',
-                  {
-                    'bg-grey-2': highlightedSuggestion === index,
-                  },
-                )}
-                onClick={e => {
-                  e.stopPropagation();
-                  onSelectUser(u);
-                }}
-                role="option"
-                aria-selected={highlightedSuggestion === index}
-              >
-                <span className="truncate">{u.username}</span>
-                <span className="text-color-text-light">{u.displayName}</span>
-              </li>
+                user={u}
+                highlighted={highlightedSuggestion === index}
+                mentionMode={mentionMode}
+                usersListboxId={usersListboxId}
+                onSelectUser={onSelectUser}
+              />
             ))}
             {users.length === 0 && (
               <li className="italic p-2" data-testid="suggestions-fallback">

diff --git a/src/sidebar/components/test/MentionSuggestionsPopover-test.js b/src/sidebar/components/test/MentionSuggestionsPopover-test.js
@@ -1,4 +1,4 @@
-import { mount } from '@hypothesis/frontend-testing';
+import { checkAccessibility, mount } from '@hypothesis/frontend-testing';
 import { useRef } from 'preact/hooks';
 import sinon from 'sinon';
 
@@ -28,6 +28,7 @@ describe('MentionSuggestionsPopover', () => {
         users={defaultUsers}
         highlightedSuggestion={0}
         onSelectUser={sinon.stub()}
+        mentionMode="username"
         {...props}
         open
       />,
@@ -90,4 +91,39 @@ describe('MentionSuggestionsPopover', () => {
       assert.calledWith(onSelectUser, defaultUsers[index]);
     });
   });
+
+  [
+    {
+      mentionMode: 'username',
+      shouldShowUsernames: true,
+    },
+    {
+      mentionMode: 'display-name',
+      shouldShowUsernames: false,
+    },
+  ].forEach(({ mentionMode, shouldShowUsernames }) => {
+    it('renders expected suggestions according to mention mode', () => {
+      const wrapper = createComponent({ mentionMode });
+
+      assert.equal(
+        wrapper.exists('[data-testid="username-one"]'),
+        shouldShowUsernames,
+      );
+      assert.equal(
+        wrapper.exists('[data-testid="username-two"]'),
+        shouldShowUsernames,
+      );
+      assert.equal(
+        wrapper.exists('[data-testid="username-three"]'),
+        shouldShowUsernames,
+      );
+    });
+  });
+
+  it(
+    'should pass a11y checks',
+    checkAccessibility({
+      content: () => createComponent(),
+    }),
+  );
 });
diff --git a/src/sidebar/helpers/mention-suggestions.ts b/src/sidebar/helpers/mention-suggestions.ts
@@ -1,6 +1,8 @@
 import type { FocusedGroupMembers } from '../store/modules/groups';
 
 export type UserItem = {
+  /** User ID in the form of acct:[username]@[authority] */
+  userid: string;
   username: string;
   displayName: string | null;
 };
@@ -29,13 +31,17 @@ export function combineUsersForMentions(
   // Once group members are loaded, we can merge them with the users who
   // already annotated the document, then deduplicate and sort the result.
   const focusedGroupUsers: UserItem[] = focusedGroupMembers.members.map(
-    ({ username, display_name: displayName }) => ({ username, displayName }),
+    ({ userid, username, display_name: displayName }) => ({
+      userid,
+      username,
+      displayName,
+    }),
   );
-  const addedUsernames = new Set<string>();
+  const addedUserIds = new Set<string>();
   const users = [...usersWhoAnnotated, ...focusedGroupUsers]
-    .filter(({ username }) => {
-      const usernameAlreadyAdded = addedUsernames.has(username);
-      addedUsernames.add(username);
+    .filter(({ userid }) => {
+      const usernameAlreadyAdded = addedUserIds.has(userid);
+      addedUserIds.add(userid);
       return !usernameAlreadyAdded;
     })
     .sort((a, b) => a.username.localeCompare(b.username));