[angular] WEB-53009 Fix rendering of documentation for JS WebSymbols

GitOrigin-RevId: 4f3d608ab31f2e2ef60b8a24c65734d22fa057d6

platform/webSymbols/api-dump-experimental.txt

@@ -545,6 +545,7 @@
 - a:getDescriptionSections():java.util.Map
 - a:getDocUrl():java.lang.String
 - a:getFootnote():java.lang.String
+- a:getHeader():java.lang.String
 - a:getIcon():javax.swing.Icon
 - a:getLibrary():java.lang.String
 - a:getName():java.lang.String
@@ -560,6 +561,7 @@
 - a:withDescriptionSection(java.lang.String,java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation
 - a:withDocUrl(java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation
 - a:withFootnote(java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation
+- a:withHeader(java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation
 - a:withIcon(javax.swing.Icon):com.intellij.webSymbols.documentation.WebSymbolDocumentation
 - a:withLibrary(java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation
 - a:withName(java.lang.String):com.intellij.webSymbols.documentation.WebSymbolDocumentation

platform/webSymbols/src/com/intellij/webSymbols/documentation/WebSymbolDocumentation.kt

@@ -80,6 +80,11 @@ interface WebSymbolDocumentation {
    */
   val footnote: @Nls String?
 
+  /**
+   * Header shown before definition
+   */
+  val header: @Nls String?
+
   fun isNotEmpty(): Boolean
 
   fun withName(name: @NlsSafe String): WebSymbolDocumentation
@@ -106,6 +111,8 @@ interface WebSymbolDocumentation {
 
   fun withFootnote(footnote: @Nls String?): WebSymbolDocumentation
 
+  fun withHeader(header: @Nls String?): WebSymbolDocumentation
+
   fun with(name: @NlsSafe String = this.name,
            definition: @NlsSafe String = this.definition,
            definitionDetails: @Nls String? = this.definitionDetails,
@@ -146,7 +153,7 @@ interface WebSymbolDocumentation {
                descriptionSections: Map<@Nls String, @Nls String> = symbol.descriptionSections,
                footnote: @Nls String? = null): WebSymbolDocumentation =
       WebSymbolDocumentationImpl(name, definition, definitionDetails, description, docUrl, apiStatus, required, defaultValue, library, icon,
-                                 descriptionSections, footnote)
+                                 descriptionSections, footnote, null)
         .let { doc: WebSymbolDocumentation ->
           WebSymbolDocumentationCustomizer.EP_NAME.extensionList.fold(doc) { documentation, customizer ->
             customizer.customize(symbol, location, documentation)

platform/webSymbols/src/com/intellij/webSymbols/documentation/impl/WebSymbolDocumentationImpl.kt

@@ -16,10 +16,12 @@ internal data class WebSymbolDocumentationImpl(override val name: String,
                                                override val library: String?,
                                                override val icon: Icon?,
                                                override val descriptionSections: Map<@Nls String, @Nls String>,
-                                               override val footnote: @Nls String?) : WebSymbolDocumentation {
+                                               override val footnote: @Nls String?,
+                                               override val header: @Nls String?) : WebSymbolDocumentation {
   override fun isNotEmpty(): Boolean =
     name != definition || description != null || docUrl != null || (apiStatus != null && apiStatus != WebSymbolApiStatus.Stable)
     || required || defaultValue != null || library != null || descriptionSections.isNotEmpty() || footnote != null
+    || header != null
 
   override fun withName(name: String): WebSymbolDocumentation =
     copy(name = name)
@@ -57,6 +59,9 @@ internal data class WebSymbolDocumentationImpl(override val name: String,
   override fun withFootnote(@Nls footnote: String?): WebSymbolDocumentation =
     copy(footnote = footnote)
 
+  override fun withHeader(header: @Nls String?): WebSymbolDocumentation =
+    copy(header = header)
+
   override fun with(name: String,
                     definition: String,
                     definitionDetails: String?,

platform/webSymbols/src/com/intellij/webSymbols/documentation/impl/WebSymbolDocumentationTargetImpl.kt

@@ -23,8 +23,10 @@ import java.awt.Image
 import java.awt.image.BufferedImage
 import javax.swing.Icon
 
-internal class WebSymbolDocumentationTargetImpl(override val symbol: WebSymbol,
-                                                override val location: PsiElement?)
+internal class WebSymbolDocumentationTargetImpl(
+  override val symbol: WebSymbol,
+  override val location: PsiElement?,
+)
   : WebSymbolDocumentationTarget {
 
   override fun createPointer(): Pointer<out DocumentationTarget> {
@@ -42,6 +44,7 @@ internal class WebSymbolDocumentationTargetImpl(override val symbol: WebSymbol,
 
       @Suppress("HardCodedStringLiteral")
       val contents = StringBuilder()
+        .appendHeader(doc)
         .appendDefinition(doc, url2ImageMap)
         .appendDescription(doc)
         .appendSections(doc)
@@ -100,6 +103,13 @@ internal class WebSymbolDocumentationTargetImpl(override val symbol: WebSymbol,
           .append('\n')
       } ?: this
 
+    private fun StringBuilder.appendHeader(doc: WebSymbolDocumentation): StringBuilder =
+      doc.header?.let {
+        append("<div class='" + DocumentationMarkup.CLASS_TOP + "'>")
+          .append(it)
+          .append("</div>\n")
+      } ?: this
+
     private fun buildSections(doc: WebSymbolDocumentation): Map<String, String> =
       LinkedHashMap(doc.descriptionSections).also { sections ->
         if (doc.required) sections[WebSymbolsBundle.message("mdn.documentation.section.isRequired")] = ""