proritize given citation names as titles (#5215)

* proritize given citation names as titles

* update changelog

* add unit test for name

* make unit tests pass

---------

Co-authored-by: Benjamin Yackley <beyackle@microsoft.com>

Author: beyackle2

CHANGELOG.md

@@ -32,6 +32,7 @@ Notes: web developers are advised to use [`~` (tilde range)](https://github.com/
 
 ### Fixed
 
+-  Read deeper into citation objects in order to provide names, in PR [#5215](https://github.com/microsoft/BotFramework-WebChat/pull/5215), by [@beyackle2](https://github.com/beyackle2)
 -  Improved performance for `useActivityWithRenderer`, in PR [#5172](https://github.com/microsoft/BotFramework-WebChat/pull/5172), by [@OEvgeny](https://github.com/OEvgeny)
 -  Fixes [#5162](https://github.com/microsoft/BotFramework-WebChat/issues/5162). Improved performance for `useActivityTreeWithRenderer`, in PR [#5163](https://github.com/microsoft/BotFramework-WebChat/pull/5163), by [@compulim](https://github.com/compulim)
 -  Fixes [#5175](https://github.com/microsoft/BotFramework-WebChat/issues/5175). `PrecompiledGlobalize.js` is emitted instead of `.cjs`, by [@compulim](https://github.com/compulim) in PR [#5181](https://github.com/microsoft/BotFramework-WebChat/pull/5181)

__tests__/__image_snapshots__/html/citation-basic-js-citation-should-display-1-snap.png

@@ -28,6 +28,7 @@
               '@context': 'https://schema.org',
               '@id': 'cite:1',
               '@type': 'Claim',
+              name: 'Should Be Visible',
               type: 'https://schema.org/Claim',
               text: 'Reprehenderit exercitation laborum labore ut. Nostrud do et ut nostrud nisi excepteur labore adipisicing nostrud nostrud ipsum id dolore. Anim aliquip incididunt incididunt sunt sit proident consectetur exercitation qui aliqua aliquip adipisicing nisi et. Id commodo labore sunt quis do aute cillum laborum veniam [proident](https://bing.com/).'
             }
@@ -36,7 +37,7 @@
 
 [1]: https://support.microsoft.com/en-us/windows/use-a-proxy-server-in-windows-03096c53-0554-4ffe-b6ab-8b1deee8dae1
 [2]: https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/configure-proxy-server-settings "Configure proxy server settings - Windows Server"
-[3]: cite:1 "Citation-1"
+[3]: cite:1 "should be hidden"
 `,
           type: 'message'
         });
@@ -71,6 +72,9 @@
         );
 
         expect(linkDefinitionItems[2].tagName).toBe('BUTTON');
+
+        expect(linkDefinitionItems[2].innerHTML).toContain('Should Be Visible');
+        expect(linkDefinitionItems[2].innerHTML).not.toContain('should be hidden');
       });
     </script>
   </body>

__tests__/__image_snapshots__/html/citation-show-modal-link-definitions-js-citation-modal-dialog-should-show-when-clicking-on-citation-in-link-definitions-1-snap.png

@@ -28,6 +28,7 @@
               '@context': 'https://schema.org',
               '@id': 'cite:1',
               '@type': 'Claim',
+              name: "Should Be Visible",
               type: 'https://schema.org/Claim',
               text: 'Reprehenderit exercitation laborum labore ut. Nostrud do et ut nostrud nisi excepteur labore adipisicing nostrud nostrud ipsum id dolore. Anim aliquip incididunt incididunt sunt sit proident consectetur exercitation qui aliqua aliquip adipisicing nisi et. Id commodo labore sunt quis do aute cillum laborum veniam [proident](https://bing.com/).'
             }
@@ -36,7 +37,7 @@
 
 [1]: https://support.microsoft.com/en-us/windows/use-a-proxy-server-in-windows-03096c53-0554-4ffe-b6ab-8b1deee8dae1
 [2]: https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/configure-proxy-server-settings "Configure proxy server settings - Windows Server"
-[3]: cite:1 "Citation-1"
+[3]: cite:1 "should be hidden"
 `,
           type: 'message'
         });

__tests__/__image_snapshots__/html/citation-show-modal-link-definitions-js-citation-modal-dialog-should-show-when-clicking-on-citation-in-link-definitions-2-snap.png

@@ -28,6 +28,7 @@
               '@context': 'https://schema.org',
               '@id': 'cite:1',
               '@type': 'Claim',
+              name: "Should Be Visible",
               type: 'https://schema.org/Claim',
               text: 'Reprehenderit exercitation laborum labore ut. Nostrud do et ut nostrud nisi excepteur labore adipisicing nostrud nostrud ipsum id dolore. Anim aliquip incididunt incididunt sunt sit proident consectetur exercitation qui aliqua aliquip adipisicing nisi et. Id commodo labore sunt quis do aute cillum laborum veniam [proident](https://bing.com/).'
             }
@@ -36,7 +37,7 @@
 
 [1]: https://support.microsoft.com/en-us/windows/use-a-proxy-server-in-windows-03096c53-0554-4ffe-b6ab-8b1deee8dae1
 [2]: https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/configure-proxy-server-settings "Configure proxy server settings - Windows Server"
-[3]: cite:1 "Citation-1"
+[3]: cite:1 "should be hidden"
 `,
           type: 'message'
         });

__tests__/__image_snapshots__/html/citation-show-modal-markdown-js-citation-modal-dialog-should-show-when-clicking-on-citation-in-markdown-1-snap.png

@@ -98,7 +98,7 @@ const MarkdownTextContent = memo(({ activity, markdown }: Props) => {
                 messageCitation?.appearance && !messageCitation.appearance.url
                   ? () =>
                       showClaimModal(
-                        markdownDefinition.title,
+                        messageCitation.appearance.name ?? markdownDefinition.title,
                         messageCitation.appearance.text,
                         messageCitation.alternateName
                       )
@@ -118,7 +118,12 @@ const MarkdownTextContent = memo(({ activity, markdown }: Props) => {
               claim: rootLevelClaim,
               key: markdownDefinition.url,
               handleClick: isCitationURL(rootLevelClaim['@id'])
-                ? () => showClaimModal(markdownDefinition.title, rootLevelClaim.text, rootLevelClaim.alternateName)
+                ? () =>
+                    showClaimModal(
+                      rootLevelClaim.name ?? markdownDefinition.title,
+                      rootLevelClaim.text,
+                      rootLevelClaim.alternateName
+                    )
                 : undefined,
               markdownDefinition
             };
@@ -180,6 +185,16 @@ const MarkdownTextContent = memo(({ activity, markdown }: Props) => {
     }
   }, [messageThing]);
 
+  // The main text of the citation entry (e.g. the title of the document). Used as the content of the main link and, if it exists, the header of the popup window.
+  const getEntryMainText = (entry: Entry) =>
+    entry.claim?.name ?? entry.claim?.appearance?.name ?? entry.markdownDefinition.title;
+
+  // Optional alternate name for the entry, used as a subtitle beneath the link
+  const getEntryBadgeName = (entry: Entry) => entry.claim?.appearance?.usageInfo?.name;
+
+  // Secondary text describing the citation, used in the a11y description (i.e. the div's title attribute)
+  const getEntryDescription = (entry: Entry) => entry.claim?.appearance?.usageInfo?.description;
+
   return (
     <div
       className={classNames('webchat__text-content', 'webchat__text-content--is-markdown', textContentStyleSet + '')}
@@ -197,14 +212,12 @@ const MarkdownTextContent = memo(({ activity, markdown }: Props) => {
         >
           {entries.map(entry => (
             <LinkDefinitionItem
-              badgeName={entry.claim?.appearance?.usageInfo?.name}
-              badgeTitle={[entry.claim?.appearance?.usageInfo?.name, entry.claim?.appearance?.usageInfo?.description]
-                .filter(Boolean)
-                .join('\n\n')}
+              badgeName={getEntryBadgeName(entry)}
+              badgeTitle={`${getEntryBadgeName(entry) ?? ''}\n\n${getEntryDescription(entry) ?? ''}`.trim()}
               identifier={entry.markdownDefinition.label}
               key={entry.key}
               onClick={entry.handleClick}
-              text={entry.markdownDefinition.title}
+              text={getEntryMainText(entry)}
               url={entry.url}
             />
           ))}

__tests__/__image_snapshots__/html/citation-show-modal-markdown-js-citation-modal-dialog-should-show-when-clicking-on-citation-in-markdown-2-snap.png

@@ -5,12 +5,22 @@ import ItemBody from './private/ItemBody';
 import extractHostnameWithSubdomain from './private/extractHostnameWithSubdomain';
 
 type Props = Readonly<{
-  badgeName?: string;
-  badgeTitle?: string;
+  // The text (usually a number) displayed to the left of the item (e.g. "1")
   identifier?: string;
-  onClick?: (event: Pick<CustomEvent, 'defaultPrevented' | 'preventDefault' | 'type'>) => void;
+
+  // The main text of the citation. This will be formatted as if it were a link. If this is nullish and a URL exists, its host will be displayed instead.
   text?: string;
+
+  // Displayed beneath the main link of the citation if it exists
+  badgeName?: string;
+
+  // Used as a tooltip and ARIA label for the item's displayed badgeName
+  badgeTitle?: string;
+
+  // If the citation is an external link, this is its destination.
   url?: string;
+
+  onClick?: (event: Pick<CustomEvent, 'defaultPrevented' | 'preventDefault' | 'type'>) => void;
 }>;
 
 const LinkDefinitionItem = memo(({ badgeName, badgeTitle, identifier, onClick, text, url }: Props) => {

__tests__/html/citation.basic.html

@@ -4,11 +4,20 @@ import Badge from './Badge';
 import OpenInNewWindowIcon from './OpenInNewWindowIcon';
 
 type Props = Readonly<{
-  badgeName?: string;
-  badgeTitle?: string;
+  // The text (usually a number) displayed at the head of the citation
   identifier?: string;
-  isExternal?: boolean;
+
+  // The text displayed as the main link of the citation
   text: string;
+
+  // If this is true, we show the "external link" icon after the link
+  isExternal?: boolean;
+
+  // The text displayed beneath the link as a description
+  badgeName?: string;
+
+  // The title of the badge, displayed as a tooltip on the item's description as well as the description's screen-reader content
+  badgeTitle?: string;
 }>;
 
 const ItemBody = memo(({ badgeName, badgeTitle, identifier, isExternal, text }: Props) => (