Add @PageImage metadata directive (#367)

Adds a new `@PageImage` directive that can be placed inside a page’s
`@Metadata` directive block to allow for customizing the images that
will be used to represent the page in the navigator, hero, and elsewhere
in the UI.

For article-only catalogs it’s likely helpful to distinguish between
articles with custom icons- in the same way Swift-DocC has different
icons for different kinds of symbol pages.

`@PageImage` accepts the following parameters:

- purpose: The purpose of the image. One of the following:
    - icon: This image should be used in place of wherever a generic
            icon for the page would usually be rendered.

    - card: This image should be used whenever rendering a card
            representing this page.

- source: A string containing the name of an image in your DocC catalog.

- alt: (optional) A string containing a description of the image.

Example:

   # Feeding a Sloth

   @metadata {
     @PageImage(purpose: icon, source: "leaf.svg", alt: "An icon representing a leaf.")
   }

`@PageImage` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#pageimage-22

Dependencies:

- swiftlang/swift-docc-render#417

Resolves rdar://97739580

Author: ethan-kusters

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -617,6 +617,14 @@ extension NavigatorIndex {
         /// Indicates if the page title should be used instead of the navigator title.
         private let usePageTitle: Bool
 
+        
+        /// Maps the icon render references in the navigator items created by this builder
+        /// to their image references.
+        ///
+        /// Use the `NavigatorItem.icon` render reference to look up the full image reference
+        /// for any custom icons used in this navigator index.
+        var iconReferences = [String : ImageReference]()
+        
         /**
          Initialize a `Builder` with the given data provider and output URL.
          - Parameters:
@@ -753,11 +761,21 @@ extension NavigatorIndex {
                 }
             }
 
-            let navigationItem = NavigatorItem(pageType: renderNode.navigatorPageType().rawValue,
-                                           languageID: language.mask,
-                                           title: title,
-                                           platformMask: platformID,
-                                           availabilityID: UInt64(availabilityID))
+            
+            if let icon = renderNode.icon,
+                let iconRenderReference = renderNode.references[icon.identifier] as? ImageReference
+            {
+                iconReferences[icon.identifier] = iconRenderReference
+            }
+            
+            let navigationItem = NavigatorItem(
+                pageType: renderNode.navigatorPageType().rawValue,
+                languageID: language.mask,
+                title: title,
+                platformMask: platformID,
+                availabilityID: UInt64(availabilityID),
+                icon: renderNode.icon
+            )
             navigationItem.path = identifierPath
 
             // Index the USR for the given identifier

Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift

@@ -47,6 +47,8 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
     /// If available, a hashed USR of this entry and its language information.
     internal var usrIdentifier: String? = nil
 
+    var icon: RenderReferenceIdentifier? = nil
+    
     /**
      Initialize a `NavigatorItem` with the given data.
 
@@ -58,13 +60,14 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - availabilityID:  The identifier of the availability information of the page.
         - path: The path to load the content.
      */
-    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String) {
+    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
         self.platformMask = platformMask
         self.availabilityID = availabilityID
         self.path = path
+        self.icon = icon
     }
 
     /**
@@ -77,12 +80,13 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - platformMask: The mask indicating for which platform the page is available.
         - availabilityID:  The identifier of the availability information of the page.
      */
-    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64) {
+    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
         self.platformMask = platformMask
         self.availabilityID = availabilityID
+        self.icon = icon
     }
 
     // MARK: - Serialization and Deserialization

Sources/SwiftDocC/Indexing/IndexJSON/Index.swift renamed to Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift

@@ -23,20 +23,45 @@ import SymbolKit
 /// `Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderIndex.spec.json`.
 public struct RenderIndex: Codable, Equatable {
     /// The current schema version of the Index JSON spec.
-    public static let currentSchemaVersion = SemanticVersion(major: 0, minor: 1, patch: 0)
+    public static let currentSchemaVersion = SemanticVersion(major: 0, minor: 1, patch: 1)
 
     /// The version of the RenderIndex spec that was followed when creating this index.
     public let schemaVersion: SemanticVersion
 
     /// A mapping of interface languages to the index nodes they contain.
     public let interfaceLanguages: [String: [Node]]
 
+    /// The values of the image references used in the documentation index.
+    public private(set) var references: [String: ImageReference]
+    
+    enum CodingKeys: CodingKey {
+        case schemaVersion
+        case interfaceLanguages
+        case references
+    }
+    
     /// Creates a new render index with the given interface language to node mapping.
     public init(
-        interfaceLanguages: [String: [Node]]
+        interfaceLanguages: [String: [Node]],
+        references: [String: ImageReference] = [:]
     ) {
         self.schemaVersion = Self.currentSchemaVersion
         self.interfaceLanguages = interfaceLanguages
+        self.references = references
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.schemaVersion, forKey: .schemaVersion)
+        try container.encode(self.interfaceLanguages, forKey: .interfaceLanguages)
+        try container.encodeIfNotEmpty(self.references, forKey: .references)
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.schemaVersion = try container.decode(SemanticVersion.self, forKey: .schemaVersion)
+        self.interfaceLanguages = try container.decode([String : [RenderIndex.Node]].self, forKey: .interfaceLanguages)
+        self.references = try container.decodeIfPresent([String : ImageReference].self, forKey: .references) ?? [:]
     }
 }
 
@@ -73,6 +98,9 @@ extension RenderIndex {
         ///
         /// Allows renderers to use a specific design treatment for render index nodes that mark the node as in beta.
         public let isBeta: Bool
+        
+        /// Reference to the image that should be used to represent this node.
+        public let icon: RenderReferenceIdentifier?
 
         enum CodingKeys: String, CodingKey {
             case title
@@ -82,6 +110,7 @@ extension RenderIndex {
             case deprecated
             case external
             case beta
+            case icon
         }
 
         public func encode(to encoder: Encoder) throws {
@@ -107,6 +136,8 @@ extension RenderIndex {
             if isBeta {
                 try container.encode(isBeta, forKey: .beta)
             }
+            
+            try container.encodeIfPresent(icon, forKey: .icon)
         }
 
         public init(from decoder: Decoder) throws {
@@ -126,6 +157,8 @@ extension RenderIndex {
 
             // `isBeta` defaults to false if it's not specified
             isBeta = try values.decodeIfPresent(Bool.self, forKey: .beta) ?? false
+            
+            icon = try values.decodeIfPresent(RenderReferenceIdentifier.self, forKey: .icon)
         }
 
         /// Creates a new node with the given title, path, type, and children.
@@ -146,7 +179,8 @@ extension RenderIndex {
             children: [Node]?,
             isDeprecated: Bool,
             isExternal: Bool,
-            isBeta: Bool
+            isBeta: Bool,
+            icon: RenderReferenceIdentifier? = nil
         ) {
             self.title = title
             self.path = path
@@ -155,14 +189,16 @@ extension RenderIndex {
             self.isDeprecated = isDeprecated
             self.isExternal = isExternal
             self.isBeta = isBeta
+            self.icon = nil
         }
 
         init(
             title: String,
             path: String,
             pageType: NavigatorIndex.PageType?,
             isDeprecated: Bool,
-            children: [Node]
+            children: [Node],
+            icon: RenderReferenceIdentifier?
         ) {
             self.title = title
             self.children = children.isEmpty ? nil : children
@@ -174,6 +210,7 @@ extension RenderIndex {
             self.isExternal = false
 
             self.isBeta = false
+            self.icon = icon
 
             guard let pageType = pageType else {
                 self.type = nil
@@ -216,7 +253,8 @@ extension RenderIndex {
                     )
                 },
                 uniquingKeysWith: +
-            )
+            ),
+            references: builder.iconReferences
         )
     }
 }
@@ -242,7 +280,8 @@ extension RenderIndex.Node {
             isDeprecated: isDeprecated,
             children: node.children.map {
                 RenderIndex.Node.fromNavigatorTreeNode($0, in: navigatorIndex, with: builder)
-            }
+            },
+            icon: node.item.icon
         )
     }
 }

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -71,10 +71,11 @@ struct DataAssetManager {
         try! NSRegularExpression(pattern: "(?!^)(?<=@)[1|2|3]x(?=\\.\\w*$)")
     }()
 
-    private mutating func referenceMetaInformationForDataURL(_ dataURL: URL, dataProvider: DocumentationContextDataProvider? = nil, bundle documentationBundle: DocumentationBundle? = nil) throws -> (reference: String, traits: DataTraitCollection) {
+    private mutating func referenceMetaInformationForDataURL(_ dataURL: URL, dataProvider: DocumentationContextDataProvider? = nil, bundle documentationBundle: DocumentationBundle? = nil) throws -> (reference: String, traits: DataTraitCollection, metadata: DataAsset.Metadata) {
         var dataReference = dataURL.path
         var traitCollection = DataTraitCollection()
 
+        var metadata = DataAsset.Metadata()
         if DocumentationContext.isFileExtension(dataURL.pathExtension, supported: .video) {
             // In case of a video read its traits: dark/light variants.
 
@@ -103,9 +104,13 @@ struct DataAssetManager {
             // Remove the display scale information from the image reference.
             dataReference = dataReference.replacingOccurrences(of: "@\(displayScale.rawValue)", with: "")
             traitCollection = .init(userInterfaceStyle: userInterfaceStyle, displayScale: displayScale)
+            
+            if dataURL.pathExtension.lowercased() == "svg" {
+                metadata.svgID = SVGIDExtractor.extractID(from: dataURL)
+            }
         }
 
-        return (reference: dataReference, traits: traitCollection)
+        return (reference: dataReference, traits: traitCollection, metadata: metadata)
     }
 
     /**
@@ -123,7 +128,7 @@ struct DataAssetManager {
             // Store the image with given scale information and display scale.
             let name = referenceURL.lastPathComponent
             storage[name, default: DataAsset()]
-                .register(dataURL, with: meta.traits)
+                .register(dataURL, with: meta.traits, metadata: meta.metadata)
 
             if name.contains(".") {
                 let nameNoExtension = referenceURL.deletingPathExtension().lastPathComponent
@@ -156,7 +161,7 @@ struct DataAssetManager {
 /// ### Asset Traits
 /// - ``DisplayScale``
 /// - ``UserInterfaceStyle``
-public struct DataAsset: Codable {
+public struct DataAsset: Codable, Equatable {
     /// A context in which you intend clients to use a data asset.
     public enum Context: String, CaseIterable, Codable {
         /// An asset that a user intends to view alongside documentation content.
@@ -172,18 +177,32 @@ public struct DataAsset: Codable {
     /// depending on the system's appearance.
     public var variants = [DataTraitCollection: URL]()
 
+    /// The metadata associated with each variant.
+    public var metadata = [URL : Metadata]()
+    
     /// The context in which you intend to use the data asset.
     public var context = Context.display
 
     /// Creates an empty asset.
     public init() {}
 
+    init(
+        variants: [DataTraitCollection : URL] = [DataTraitCollection: URL](),
+        metadata: [URL : DataAsset.Metadata] = [URL : Metadata](),
+        context: DataAsset.Context = Context.display
+    ) {
+        self.variants = variants
+        self.metadata = metadata
+        self.context = context
+    }
+    
     /// Registers a variant of the asset.
     /// - Parameters:
     ///   - url: The location of the variant.
     ///   - traitCollection: The trait collection associated with the variant.
-    public mutating func register(_ url: URL, with traitCollection: DataTraitCollection) {
+    public mutating func register(_ url: URL, with traitCollection: DataTraitCollection, metadata: Metadata = Metadata()) {
         variants[traitCollection] = url
+        self.metadata[url] = metadata
     }
 
     /// Returns the data that is registered to the data asset that best matches the given trait collection.
@@ -210,6 +229,21 @@ public struct DataAsset: Codable {
 
 }
 
+extension DataAsset {
+    /// Metadata specific to this data asset.
+    public struct Metadata: Codable, Equatable {
+        /// The first ID found in the SVG asset.
+        ///
+        /// This value is nil if the data asset is not an SVG or if it is an SVG that does not contain an ID.
+        public var svgID: String?
+        
+        /// Create a new data asset metadata with the given SVG ID.
+        public init(svgID: String? = nil) {
+            self.svgID = svgID
+        }
+    }
+}
+
 /// A collection of environment traits for an asset variant.
 ///
 /// Traits describe properties of a rendering environment, such as a user-interface style (light or dark mode) and display-scale

Sources/SwiftDocC/Infrastructure/Bundle Assets/SVGIDExtractor.swift

@@ -0,0 +1,66 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 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 Foundation
+
+// On non-Darwin platforms, Foundation's XML support is vended as a separate module:
+// https://github.com/apple/swift-corelibs-foundation/blob/main/Docs/ReleaseNotes_Swift5.md#dependency-management
+#if canImport(FoundationXML)
+import FoundationXML
+#endif
+
+/// A basic XML parser that extracts the first `id` attribute found in the given SVG.
+///
+/// This is a single-purpose tool and should not be used for general-purpose SVG parsing.
+enum SVGIDExtractor {
+    /// Extracts an SVG ID from the given data.
+    ///
+    /// Exposed for testing. The sibling `extractID(from: URL)` method is intended to be
+    /// used within SwiftDocC.
+    static func _extractID(from data: Data) -> String? {
+        let delegate = SVGIDParserDelegate()
+        let svgParser = XMLParser(data: data)
+        svgParser.delegate = delegate
+        svgParser.parse()
+        
+        return delegate.id
+    }
+    
+    /// Returns the first `id` attribute found in the given SVG, if any.
+    ///
+    /// Returns nil if any errors are encountered or if an `id` attribute is
+    /// not found in the given SVG.
+    static func extractID(from svg: URL) -> String? {
+        guard let data = try? Data(contentsOf: svg) else {
+            return nil
+        }
+        
+        return _extractID(from: data)
+    }
+}
+
+private class SVGIDParserDelegate: NSObject, XMLParserDelegate {
+    var id: String?
+    
+    func parser(
+        _ parser: XMLParser,
+        didStartElement elementName: String,
+        namespaceURI: String?,
+        qualifiedName qName: String?,
+        attributes attributeDict: [String : String] = [:]
+    ) {
+        guard let id = attributeDict["id"] ?? attributeDict["ID"] ?? attributeDict["iD"] ?? attributeDict["Id"] else {
+            return
+        }
+        
+        self.id = id
+        parser.abortParsing()
+    }
+}