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}
             />
           ))}