Highlight unique components of overloaded declarations (#841)

Resolves: rdar://128997251

Co-authored-by: Vera Mitchell <[email protected]>

src/components/DocumentationTopic/PrimaryContent/DeclarationList.vue

@@ -195,6 +195,15 @@ export default {
   }
 }
 
+// don't highlight tokens in initial declaration until the user has explicitly
+// expanded a list of overloaded declarations — this rule could be simplified
+// in the future if the HTML is restructured to have an expanded state class for
+// the whole list instead of having it on each declaration
+.declaration-pill:not(.declaration-pill--expanded):deep(.highlighted) {
+  background: unset;
+  font-weight: normal;
+}
+
 .declaration-pill--expanded {
   transition-timing-function: linear;
   transition-property: opacity, height;
@@ -218,7 +227,7 @@ export default {
     border-color: var(--color-focus-border-color, var(--color-focus-border-color));
   }
 
-  :not(.selected-declaration) {
+  .source:not(.selected-declaration) {
     background: unset;
   }
 

src/components/DocumentationTopic/PrimaryContent/DeclarationToken.vue

@@ -14,6 +14,7 @@ import ChangedToken from './DeclarationToken/ChangedToken.vue';
 import LinkableToken from './DeclarationToken/LinkableToken.vue';
 import RawText from './DeclarationToken/RawText.vue';
 import SyntaxToken from './DeclarationToken/SyntaxToken.vue';
+import Highlighted from './DeclarationToken/Highlighted.vue';
 
 const TokenKind = {
   attribute: 'attribute',
@@ -27,13 +28,14 @@ const TokenKind = {
   string: 'string',
   text: 'text',
   typeIdentifier: 'typeIdentifier',
+  highlightDiff: 'highlightDiff',
   added: 'added',
   removed: 'removed',
 };
 
 export default {
   name: 'DeclarationToken',
-  render(createElement) {
+  render: function _render(createElement) {
     const {
       kind,
       text,
@@ -69,6 +71,10 @@ export default {
     case TokenKind.added:
     case TokenKind.removed:
       return createElement(ChangedToken, { props: { tokens, kind } });
+    case TokenKind.highlightDiff:
+      return createElement(Highlighted, {}, (tokens || []).map(token => (
+        _render.bind(token)(createElement)
+      )));
     default: {
       const props = {
         kind,

src/components/DocumentationTopic/PrimaryContent/DeclarationToken/Highlighted.vue

@@ -0,0 +1,23 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2024 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <strong class="highlighted"><slot /></strong>
+</template>
+
+<script>
+export default { name: 'Highlighted' };
+</script>
+
+<style scoped lang="scss">
+.highlighted {
+  background: var(--color-syntax-highlighted, mark);
+}
+</style>

src/styles/core/colors/_dark.scss

@@ -63,6 +63,7 @@
   --color-syntax-comments: rgb(127, 140, 152);
   --color-syntax-documentation-markup: rgb(127, 140, 152);
   --color-syntax-documentation-markup-keywords: rgb(163, 177, 191);
+  --color-syntax-highlighted: rgba(0, 113, 227, 0.6);
   --color-syntax-keywords: rgb(255, 122, 178);
   --color-syntax-marks: rgb(255, 255, 255);
   --color-syntax-numbers: rgb(217, 201, 124);

src/styles/core/colors/_light.scss

@@ -152,6 +152,7 @@
   --color-syntax-documentation-markup: rgb(80, 99, 117);
   --color-syntax-documentation-markup-keywords: rgb(80, 99, 117);
   --color-syntax-heading: rgb(186, 45, 162);
+  --color-syntax-highlighted: rgba(0, 113, 227, 0.2);
   --color-syntax-keywords: rgb(173, 61, 164);
   --color-syntax-marks: rgb(0, 0, 0);
   --color-syntax-numbers: rgb(39, 42, 216);

tests/unit/components/DocumentationTopic/PrimaryContent/DeclarationToken.spec.js

@@ -18,6 +18,8 @@ import SyntaxToken
 import LinkableToken
   from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationToken/LinkableToken.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import Highlighted
+  from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationToken/Highlighted.vue';
 
 const { TokenKind } = DeclarationToken.constants;
 
@@ -58,6 +60,7 @@ describe('DeclarationToken', () => {
     otherKinds.delete(TokenKind.typeIdentifier);
     otherKinds.delete(TokenKind.removed);
     otherKinds.delete(TokenKind.added);
+    otherKinds.delete(TokenKind.highlightDiff);
 
     otherKinds.forEach((kind) => {
       const propsData = { kind, text: 'foo' };
@@ -125,4 +128,29 @@ describe('DeclarationToken', () => {
     expect(link.text()).toBe(propsData.text);
     expect(link.classes()).toContain('attribute-link');
   });
+
+  it('renders a `Highlighted` for `highlightDiff` tokens', () => {
+    const stubs = { RawText };
+    const propsData = {
+      kind: TokenKind.highlightDiff,
+      tokens: [
+        {
+          kind: TokenKind.text,
+          text: 'foo',
+        },
+        {
+          kind: TokenKind.text,
+          text: 'bar',
+        },
+      ],
+    };
+    const wrapper = mountToken({ propsData, stubs });
+    const highlighted = wrapper.find(Highlighted);
+    expect(highlighted.exists()).toBe(true);
+
+    const textTokens = highlighted.findAll(RawText);
+    expect(textTokens.length).toBe(propsData.tokens.length);
+    expect(textTokens.at(0).props('text')).toBe(propsData.tokens[0].text);
+    expect(textTokens.at(1).props('text')).toBe(propsData.tokens[1].text);
+  });
 });

tests/unit/components/DocumentationTopic/PrimaryContent/DeclarationToken/Highlighted.spec.js

@@ -0,0 +1,22 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2024 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+import { shallowMount } from '@vue/test-utils';
+import Highlighted from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationToken/Highlighted.vue';
+
+describe('Highlighted', () => {
+  it('renders slotted content using strong.highlighted', () => {
+    const slots = { default: 'hello, world' };
+    const wrapper = shallowMount(Highlighted, { slots });
+
+    const strong = wrapper.find('strong.highlighted');
+    expect(strong.exists()).toBe(true);
+    expect(strong.text()).toBe(slots.default);
+  });
+});