Extra tags and Social Card integration in the Infrastructure package (#28)

This PR contains the work done to extends the `Page` protocol with the head tags that control search snippets and link previews: a meta description, a canonical URL, and a social card rendered as _Open Graph_ and _Twitter_ meta tags. All three are optional with nil defaults, so existing conformers compile and render unchanged.

Reviewed-on: rock-n-code/loud-amsterdam#28
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>

Packages/Infrastructure/Sources/Public/Protocols/Page.swift

@@ -4,8 +4,8 @@ import Foundation
 /// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
 ///
 /// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
-/// rest of the document around them: the viewport declaration and stylesheet links followed by the metadata in the head, and the content followed by
-/// the script tags in the body.
+/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, and the metadata followed by the
+/// stylesheet links in the head, and the content followed by the script tags in the body.
 public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Associated types
@@ -21,6 +21,9 @@ public protocol Page: HTMLDocument, Sendable {
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     var assetVersion: String? { get }
 
+    /// The canonical URL the page is served at, rendered as a `link rel="canonical"` tag in the document head, or `nil` (the default) to omit the tag.
+    var canonicalURL: String? { get }
+
     /// The page's markup, rendered before the ``scripts``.
     @HTMLBuilder
     var content: Content { get }
@@ -28,30 +31,41 @@ public protocol Page: HTMLDocument, Sendable {
     /// The locale the page content is localized to.
     var locale: Locale { get }
 
-    /// The markup placed in the document head after the ``stylesheets``: icon and manifest
-    /// links, extra meta tags, and the like.
+    /// The markup placed in the document head before the ``stylesheets`` links: icon and manifest links, extra meta tags, and the like.
     @HTMLBuilder
     var metadata: Metadata { get }
 
     /// The scripts loaded at the end of the document body, in order.
     var scripts: [any Asset] { get }
 
+    /// The card controlling the page's link previews, rendered as Open Graph and Twitter meta tags in the document head, or `nil` (the default)
+    /// to omit them.
+    var socialCard: SocialCard? { get }
+
     /// The stylesheets linked in the document head, in order.
     var stylesheets: [any Asset] { get }
 
+    /// The page's summary, rendered as a `meta name="description"` tag in the document head, or `nil` (the default) to omit the tag.
+    var summary: String? { get }
+
 }
 
 // MARK: - Implementations
 
 public extension Page {
-
+    
     // MARK: Computed
-
+    
+    /// The canonical URL is omitted unless the page provides one.
+    var canonicalURL: String? {
+        nil
+    }
+    
     /// The page ``content`` followed by its ``scripts``.
     @HTMLBuilder
     var body: some HTML {
         content
-
+        
         for file in scripts {
             script(.src(file.urlPath(
                 for: .js,
@@ -59,8 +73,9 @@ public extension Page {
             ))) {}
         }
     }
-
-    /// The viewport declaration and ``stylesheets`` links followed by the ``metadata``, placed in the document head.
+    
+    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags (when provided), and the ``metadata``
+    /// followed by the ``stylesheets`` links, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
@@ -70,9 +85,35 @@ public extension Page {
             .name(.viewport),
             .content("width=device-width, initial-scale=1")
         )
+        
+        if let summary {
+            meta(
+                .name(.description),
+                .content(summary)
+            )
+        }
+        
+        if let canonicalURL {
+            link(
+                .rel("canonical"),
+                .href(canonicalURL)
+            )
+        }
+
+        if let socialCard {
+            for tag in socialCard.tags {
+                meta(
+                    .custom(
+                        name: tag.attribute.rawValue,
+                        value: tag.name.rawValue
+                    ),
+                    .content(tag.content)
+                )
+            }
+        }
 
         metadata
-
+        
         for file in stylesheets {
             link(
                 .rel(.stylesheet),
@@ -83,5 +124,15 @@ public extension Page {
             )
         }
     }
+    
+    /// The social card is omitted unless the page provides one.
+    var socialCard: SocialCard? {
+        nil
+    }
 
+    /// The summary is omitted unless the page provides one.
+    var summary: String? {
+        nil
+    }
+    
 }