rock-n-code/ccn
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

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

Browse Source 
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>
This commit is contained in:
javier
2026-08-01 10:57:29 +00:00
committed by javier
parent ea00b94841
commit efc933d5d0
8 changed files with 483 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+61 -10
View File
@@ -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
}
}
Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
+138
View File
@@ -0,0 +1,138 @@
/// The content of a page's link-preview card, rendered as Open Graph and Twitter meta tags in the document head.
///
/// The card carries the facts a link scraper reads — the page's title, summary, URL, and share image — and derives the meta ``tags`` expressing
/// them. Scrapers require absolute URLs, so the card takes ``url`` and ``Image/url`` fully formed; composing them from an origin and a versioned
/// asset path stays with the page providing the card.
public struct SocialCard: Sendable {
// MARK: Properties
/// The card's share image, or `nil` to omit its tags.
public let image: Image?
/// The locale of the card's text, or `nil` to omit its tag.
///
/// Open Graph specifies the `language_TERRITORY` form (e.g. `en_US`); scrapers also accept a bare language code (e.g. `en`).
public let locale: String?
/// The name of the site the card belongs to, or `nil` to omit its tag.
public let siteName: String?
/// The layout a Twitter card scraper gives the card.
public let style: Style
/// The card's summary, or `nil` to omit its tag.
public let summary: String?
/// The card's title.
public let title: String
/// The Open Graph type of the object the card describes.
public let type: String
/// The absolute URL the card's page is served at, or `nil` to omit its tag.
public let url: String?
// MARK: Initializers
/// Creates a link-preview card.
/// - Parameters:
/// - title: the card's title.
/// - summary: the card's summary, or `nil` (the default) to omit its tag.
/// - url: the absolute URL the card's page is served at, or `nil` (the default) to omit its tag.
/// - siteName: the name of the site the card belongs to, or `nil` (the default) to omit its tag.
/// - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_US`), or `nil` (the default)
/// to omit its tag.
/// - image: the card's share image, or `nil` (the default) to omit its tags.
/// - type: the Open Graph type of the object the card describes. Defaults to `website`.
/// - style: the layout a Twitter card scraper gives the card. Defaults to ``Style/summaryLargeImage``.
public init(
title: String,
summary: String? = nil,
url: String? = nil,
siteName: String? = nil,
locale: String? = nil,
image: Image? = nil,
type: String = "website",
style: Style = .summaryLargeImage
) {
self.image = image
self.locale = locale
self.siteName = siteName
self.style = style
self.summary = summary
self.title = title
self.type = type
self.url = url
}
// MARK: Computed
/// The card's meta tags, in a stable order: the Open Graph type, site name, title, description, URL, and locale, then the image group, and
/// the Twitter card style last. A tag whose fact the card does not carry is left out.
public var tags: [SocialCardTag] {
let tags: [SocialCardTag?] = [
SocialCardTag(
attribute: .property,
content: type,
name: .type
),
siteName.map {
SocialCardTag(
attribute: .property,
content: $0,
name: .siteName
)
},
SocialCardTag(
attribute: .property,
content: title,
name: .title
),
summary.map {
SocialCardTag(
attribute: .property,
content: $0,
name: .description
)
},
url.map {
SocialCardTag(
attribute: .property,
content: $0,
name: .url
)
},
locale.map {
SocialCardTag(
attribute: .property,
content: $0,
name: .locale
)
},
] + (image?.tags ?? []) + [
SocialCardTag(
attribute: .name,
content: style.rawValue,
name: .twitter
),
]
return tags.compactMap { $0 }
}
}
// MARK: - Enumerations
public extension SocialCard {
/// The layout a Twitter card scraper gives a ``SocialCard``.
enum Style: String, Sendable {
/// A compact card with a small thumbnail.
case summary
/// A card with a large image above the text.
case summaryLargeImage = "summary_large_image"
}
}
Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
+72
View File
@@ -0,0 +1,72 @@
extension SocialCard {
/// The share image of a ``SocialCard``.
public struct Image: Sendable {
// MARK: Properties
/// The image's text for assistive technologies, or `nil` to omit it.
public let alt: String?
/// The image's height in pixels, letting scrapers lay the card out before fetching the image.
public let height: Int
/// The absolute URL the image is served at.
public let url: String
/// The image's width in pixels, letting scrapers lay the card out before fetching the image.
public let width: Int
// MARK: Initializers
/// Creates a share image.
/// - Parameters:
/// - url: the absolute URL the image is served at.
/// - width: the image's width in pixels.
/// - height: the image's height in pixels.
/// - alt: the image's text for assistive technologies, or `nil` (the default) to omit it.
public init(
url: String,
width: Int,
height: Int,
alt: String? = nil
) {
self.alt = alt
self.height = height
self.url = url
self.width = width
}
// MARK: Computed
/// The image's meta tags, in a stable order: its URL, width, and height, then its alt text when it carries one.
public var tags: [SocialCardTag] {
let tags: [SocialCardTag?] = [
SocialCardTag(
attribute: .property,
content: url,
name: .image
),
SocialCardTag(
attribute: .property,
content: String(width),
name: .imageWidth
),
SocialCardTag(
attribute: .property,
content: String(height),
name: .imageHeight
),
alt.map {
SocialCardTag(
attribute: .property,
content: $0,
name: .imageAlt
)
},
]
return tags.compactMap { $0 }
}
}
}
Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
+55
View File
@@ -0,0 +1,55 @@
/// A head meta tag of a ``SocialCard``: which attribute keys it, and its name and content.
public struct SocialCardTag: Equatable, Sendable {
// MARK: Properties
/// The attribute the tag is keyed by.
public let attribute: Attribute
/// The tag's value.
public let content: String
/// The tag's name.
public let name: Name
}
// MARK: - Enumerations
extension SocialCardTag {
/// The meta attribute a ``SocialCardTag`` is keyed by, named by its raw value.
public enum Attribute: String, Sendable {
/// The `name` attribute, keying the Twitter tags.
case name
/// The `property` attribute, keying the Open Graph tags.
case property
}
/// The name of a ``SocialCardTag``, carried in its raw value.
public enum Name: String, Sendable {
/// The `og:description` tag, carrying the card's summary.
case description = "og:description"
/// The `og:image` tag, carrying the share image's absolute URL.
case image = "og:image"
/// The `og:image:alt` tag, carrying the share image's text for assistive technologies.
case imageAlt = "og:image:alt"
/// The `og:image:width` tag, carrying the share image's width in pixels.
case imageWidth = "og:image:width"
/// The `og:image:height` tag, carrying the share image's height in pixels.
case imageHeight = "og:image:height"
/// The `og:locale` tag, carrying the locale of the card's text.
case locale = "og:locale"
/// The `og:site_name` tag, carrying the name of the site the card belongs to.
case siteName = "og:site_name"
/// The `og:title` tag, carrying the card's title.
case title = "og:title"
/// The `twitter:card` tag, carrying the layout a Twitter card scraper gives the card.
case twitter = "twitter:card"
/// The `og:type` tag, carrying the Open Graph type of the object the card describes.
case type = "og:type"
/// The `og:url` tag, carrying the absolute URL the card's page is served at.
case url = "og:url"
}
}
Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+50
View File
@@ -47,6 +47,56 @@ struct PageTests {
#expect(content.lowerBound < script.lowerBound)
}
@Test
func `omits the summary and canonical tags by default`() {
let html = StubPage().render()
#expect(!html.contains(#"name="description""#))
#expect(!html.contains(#"rel="canonical""#))
}
@Test
func `renders the summary and canonical tags when provided`() {
let html = StubPage(
canonicalURL: "https://stub.example/",
summary: "A stub page."
).render()
#expect(html.contains(#"<meta name="description" content="A stub page.">"#))
#expect(html.contains(#"<link rel="canonical" href="https://stub.example/">"#))
}
@Test
func `omits the social card tags by default`() {
let html = StubPage().render()
#expect(!html.contains(#"property="og:"#))
#expect(!html.contains(#"name="twitter:card""#))
}
@Test
func `renders the social card tags when provided`() {
let html = StubPage(socialCard: .init(
title: "Stub Page",
summary: "A stub page.",
url: "https://stub.example/",
image: .init(
url: "https://stub.example/img/card.png",
width: 2400,
height: 1260
)
)).render()
#expect(html.contains(#"<meta property="og:type" content="website">"#))
#expect(html.contains(#"<meta property="og:title" content="Stub Page">"#))
#expect(html.contains(#"<meta property="og:description" content="A stub page.">"#))
#expect(html.contains(#"<meta property="og:url" content="https://stub.example/">"#))
#expect(html.contains(#"<meta property="og:image" content="https://stub.example/img/card.png">"#))
#expect(html.contains(#"<meta property="og:image:width" content="2400">"#))
#expect(html.contains(#"<meta property="og:image:height" content="1260">"#))
#expect(html.contains(#"<meta name="twitter:card" content="summary_large_image">"#))
}
@Test
func `appends the version token to the asset URLs`() {
let html = StubPage(assetVersion: "0123456789abcdef").render()
Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
+84
View File
@@ -0,0 +1,84 @@
import Testing
@testable import Infrastructure
@Suite(
"SocialCard type",
.tags(.type)
)
struct SocialCardTests {
// MARK: Functional tests
@Test
func `derives the full tag list from a complete card`() {
let card = SocialCard(
title: "A Title",
summary: "A summary.",
url: "https://site.example/",
siteName: "A Site",
locale: "en",
image: .init(
url: "https://site.example/img/card.png",
width: 2400,
height: 1260,
alt: "An image."
)
)
#expect(card.tags == [
.init(attribute: .property, content: "website", name: .type),
.init(attribute: .property, content: "A Site", name: .siteName),
.init(attribute: .property, content: "A Title", name: .title),
.init(attribute: .property, content: "A summary.", name: .description),
.init(attribute: .property, content: "https://site.example/", name: .url),
.init(attribute: .property, content: "en", name: .locale),
.init(attribute: .property, content: "https://site.example/img/card.png", name: .image),
.init(attribute: .property, content: "2400", name: .imageWidth),
.init(attribute: .property, content: "1260", name: .imageHeight),
.init(attribute: .property, content: "An image.", name: .imageAlt),
.init(attribute: .name, content: "summary_large_image", name: .twitter),
])
}
@Test
func `omits the tags of the facts a minimal card does not carry`() {
let card = SocialCard(title: "A Title")
#expect(card.tags == [
.init(attribute: .property, content: "website", name: .type),
.init(attribute: .property, content: "A Title", name: .title),
.init(attribute: .name, content: "summary_large_image", name: .twitter),
])
}
@Test
func `omits the image alt tag when the image carries none`() {
let card = SocialCard(
title: "A Title",
image: .init(
url: "https://site.example/img/card.png",
width: 2400,
height: 1260
)
)
let names = card.tags.map(\.name)
#expect(names.contains(.image))
#expect(!names.contains(.imageAlt))
}
@Test
func `carries the type and style it is given`() {
let card = SocialCard(
title: "A Title",
type: "article",
style: .summary
)
#expect(card.tags.contains(.init(attribute: .property, content: "article", name: .type)))
#expect(card.tags.contains(.init(attribute: .name, content: "summary", name: .twitter)))
}
}
Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
+1 -1
View File
@@ -9,6 +9,6 @@ extension Tag {
@Tag static var middleware: Tag
/// Tests exercising a protocol scaffolding of the Infrastructure package.
@Tag static var `protocol`: Tag
/// Tests exercising an internal type of the Infrastructure package.
/// Tests exercising a type of the Infrastructure package.
@Tag static var type: Tag
}
Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
+22 -1
View File
@@ -10,9 +10,18 @@ struct StubPage: Page {
/// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
let assetVersion: String?
/// The canonical URL rendered in the document head, or `nil` to omit it.
let canonicalURL: String?
/// The locale the page content is localized to.
let locale: Locale
/// The card rendered as link-preview tags in the document head, or `nil` to omit them.
let socialCard: SocialCard?
/// The summary rendered in the document head, or `nil` to omit it.
let summary: String?
// MARK: Initializers
/// Creates a stub page.
@@ -20,12 +29,24 @@ struct StubPage: Page {
/// - locale: the locale the page content is localized to. Defaults to `en`.
/// - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
/// default) to leave them unversioned.
/// - canonicalURL: the canonical URL rendered in the document head, or `nil` (the default)
/// to omit it.
/// - socialCard: the card rendered as link-preview tags in the document head, or `nil`
/// (the default) to omit them.
/// - summary: the summary rendered in the document head, or `nil` (the default)
/// to omit it.
init(
locale: Locale = .init(identifier: "en"),
assetVersion: String? = nil
assetVersion: String? = nil,
canonicalURL: String? = nil,
socialCard: SocialCard? = nil,
summary: String? = nil
) {
self.assetVersion = assetVersion
self.canonicalURL = canonicalURL
self.locale = locale
self.socialCard = socialCard
self.summary = summary
}
// MARK: Computed