feat(annotate_citations): use aria-attributes

Solves #1178

Use aria-description on the anchor tag for a resolved citation. The description uses the case name, truncated if it is too long

cl/citations/annotate_citations.py

@@ -6,6 +6,7 @@
 
 from cl.citations.match_citations import NO_MATCH_RESOURCE
 from cl.citations.types import MatchedResourceType, SupportedCitationType
+from cl.lib.string_utils import trunc
 from cl.search.models import Opinion, RECAPDocument
 
 
@@ -43,6 +44,26 @@ def get_and_clean_opinion_text(document: Opinion | RECAPDocument) -> None:
         document.source_is_html = False
 
 
+def get_case_name_for_aria_attributes(
+    document: Opinion | RECAPDocument,
+) -> str:
+    """Get a short or truncated case name of the cluster or docket
+    the document belongs to
+
+    :param document: The Opinion or RECAPDocument whose text should be parsed
+    :return: The truncated case name
+    """
+    if isinstance(document, Opinion):
+        case_name = (
+            document.cluster.case_name_short or document.cluster.case_name
+        )
+    else:
+        docket = document.docket_entry.docket
+        case_name = docket.case_name_short or docket.case_name
+
+    return trunc(case_name, 60, "...")
+
+
 def generate_annotations(
     citation_resolutions: Dict[
         MatchedResourceType, List[SupportedCitationType]
@@ -61,8 +82,12 @@ def generate_annotations(
                 "</span>",
             ]
         else:  # If successfully matched...
+            case_name = get_case_name_for_aria_attributes(opinion)
             annotation = [
-                f'<span class="citation" data-id="{opinion.pk}"><a href="{opinion.cluster.get_absolute_url()}">',
+                f'<span class="citation" data-id="{opinion.pk}">'
+                f'<a href="{opinion.cluster.get_absolute_url()}"'
+                f' aria-description="Citation for case: {case_name}"'
+                ">",
                 "</a></span>",
             ]
         for c in citations:

cl/citations/tests.py

@@ -315,24 +315,26 @@ def test_make_html_from_matched_citation_objects(self) -> None:
         # test the rendering of citation objects that we assert are correctly
         # matched. (No matching is performed in the previous cases.)
         # fmt: off
-
+        case_name = "Example vs. Example"
+        aria_description = f'aria-description="Citation for case: {case_name}"'
         test_pairs = [
             # Id. citation with page number ("Id., at 123, 124")
             ('asdf, Id., at 123, 124. Lorem ipsum dolor sit amet',
              '<pre class="inline">asdf, </pre><span class="citation" data-id="'
-             'MATCH_ID"><a href="MATCH_URL">Id., at 123, 124</a></span><pre '
-             'class="inline">. Lorem ipsum dolor sit amet</pre>'),
+             f'MATCH_ID"><a href="MATCH_URL" {aria_description}>'
+             'Id., at 123, 124</a></span><pre class="inline">.'
+             'Lorem ipsum dolor sit amet</pre>'),
 
             # Id. citation with complex page number ("Id. @ 123:1, ¶¶ 124")
             ('asdf, Id. @ 123:1, ¶¶ 124. Lorem ipsum dolor sit amet',
              '<pre class="inline">asdf, </pre><span class="citation" data-id='
-             '"MATCH_ID"><a href="MATCH_URL">Id.</a></span><pre class='
+             f'"MATCH_ID"><a href="MATCH_URL" {aria_description}>Id.</a></span><pre class='
              '"inline"> @ 123:1, ¶¶ 124. Lorem ipsum dolor sit amet</pre>'),
 
             # Id. citation without page number ("Id. Something else")
             ('asdf, Id. Lorem ipsum dolor sit amet',
              '<pre class="inline">asdf, </pre><span class="citation" data-id="'
-             'MATCH_ID"><a href="MATCH_URL">Id.</a></span><pre class="inline">'
+             f'MATCH_ID"><a href="MATCH_URL" {aria_description}>Id.</a></span><pre class="inline">'
              ' Lorem ipsum dolor sit amet</pre>'),
         ]
 
@@ -355,7 +357,9 @@ def test_make_html_from_matched_citation_objects(self) -> None:
                 # to receive. Also make sure that the "matched" opinion is
                 # mocked appropriately.
                 opinion.pk = "MATCH_ID"
-                opinion.cluster = Mock(OpinionCluster(id=24601))
+                opinion.cluster = Mock(
+                    OpinionCluster(id=24601, case_name=case_name)
+                )
                 opinion.cluster.get_absolute_url.return_value = "MATCH_URL"
                 citation_resolutions = {opinion: citations}