fix: various qol changes

fix: various qol changes

Author: maclong9

Sources/WebUI/Core/Document.swift

@@ -1,12 +1,19 @@
 import Foundation
 import Logging
 
+public enum ScriptAttribute: String {
+  /// Defers downloading of the script to during page pare
+  case `defer`
+  /// Causes the script to run as soon as it's available
+  case async
+}
+
 /// Represents an immutable HTML document with metadata and content.
 public struct Document {
   private let logger = Logger(label: "com.webui.document")
   public let path: String?
   public var metadata: Metadata
-  public var scripts: [String]?
+  public var scripts: [String: ScriptAttribute?]?
   public var stylesheets: [String]?
   public var theme: Theme?
   public let head: String?
@@ -30,23 +37,26 @@ public struct Document {
   public init(
     path: String? = nil,
     metadata: Metadata,
-    scripts: [String]? = nil,
+    scripts: [String: ScriptAttribute?]? = nil,
     stylesheets: [String]? = nil,
     theme: Theme? = nil,
     head: String? = nil,
     @HTMLBuilder content: @escaping () -> [any HTML]
   ) {
-    self.path = path
     self.metadata = metadata
+    self.path = path ?? metadata.title?.pathFormatted()
     self.scripts = scripts
     self.stylesheets = stylesheets
     self.theme = theme
     self.head = head
     self.contentBuilder = content
 
-    logger.debug("Document initialized with path: \(path ?? "index"), title: \(metadata.pageTitle)")
+    logger.debug(
+      "Document initialized with path: \(path ?? "index"), title: \(metadata.pageTitle)"
+    )
     logger.trace(
-      "Document has \(scripts?.count ?? 0) scripts, \(stylesheets?.count ?? 0) stylesheets")
+      "Document has \(scripts?.count ?? 0) scripts, \(stylesheets?.count ?? 0) stylesheets"
+    )
   }
 
   /// Renders the document as a complete HTML string.
@@ -63,21 +73,18 @@ public struct Document {
     if let image = metadata.image, !image.isEmpty {
       logger.trace("Adding og:image meta tag: \(image)")
       optionalMetaTags.append(
-        "<meta property=\"og:image\" content=\"\(image)\">")
+        "<meta property=\"og:image\" content=\"\(image)\">"
+      )
     }
     if let author = metadata.author, !author.isEmpty {
       logger.trace("Adding author meta tag: \(author)")
       optionalMetaTags.append("<meta name=\"author\" content=\"\(author)\">")
     }
-    if let type = metadata.type {
-      logger.trace("Adding og:type meta tag: \(type.rawValue)")
-      optionalMetaTags.append(
-        "<meta property=\"og:type\" content=\"\(type.rawValue)\">")
-    }
     if let twitter = metadata.twitter, !twitter.isEmpty {
       logger.trace("Adding twitter meta tag: \(twitter)")
       optionalMetaTags.append(
-        "<meta name=\"twitter:creator\" content=\"@\(twitter)\">")
+        "<meta name=\"twitter:creator\" content=\"@\(twitter)\">"
+      )
     }
     if let keywords = metadata.keywords, !keywords.isEmpty {
       logger.trace("Adding keywords meta tag with \(keywords.count) keywords")
@@ -97,14 +104,17 @@ public struct Document {
     if let scripts = scripts {
       logger.trace("Adding \(scripts.count) script tags")
       for script in scripts {
-        optionalMetaTags.append("<script src=\"\(script)\"></script>")
+        optionalMetaTags.append(
+          "<script \(script.value?.rawValue ?? "") src=\"\(script.key)\"></script>"
+        )
       }
     }
     if let stylesheets = stylesheets {
       logger.trace("Adding \(stylesheets.count) stylesheet links")
       for stylesheet in stylesheets {
         optionalMetaTags.append(
-          "<link rel=\"stylesheet\" href=\"\(stylesheet)\">")
+          "<link rel=\"stylesheet\" href=\"\(stylesheet)\">"
+        )
       }
     }
 
@@ -117,6 +127,7 @@ public struct Document {
           <meta property="og:title" content="\(metadata.pageTitle)">
           <meta name="description" content="\(metadata.description)">
           <meta property="og:description" content="\(metadata.description)">
+          "<meta property=\"og:type\" content=\"\(metadata.type.rawValue)\">"
           <meta name="twitter:card" content="summary_large_image">
           \(optionalMetaTags.joined(separator: "\n"))
           <script src="https://unpkg.com/@tailwindcss/browser@4"></script>

Sources/WebUI/Core/Metadata.swift

@@ -39,7 +39,7 @@ public struct Metadata {
   public var keywords: [String]?
   public var twitter: String?
   public var locale: Locale
-  public var type: ContentType?
+  public var type: ContentType
   public var themeColor: ThemeColor?
 
   /// Creates metadata for a document’s head section.
@@ -54,7 +54,7 @@ public struct Metadata {
   ///   - keywords: SEO keywords, optional.
   ///   - twitter: Twitter handle without "@", optional.
   ///   - locale: Language setting, defaults to `.en`.
-  ///   - type: Open Graph content type, optional.
+  ///   - type: Open Graph content type, defaults to `.website`.
   ///   - themeColor: Theme colors for light and dark modes, optional.
   public init(
     site: String? = nil,
@@ -67,7 +67,7 @@ public struct Metadata {
     keywords: [String]? = nil,
     twitter: String? = nil,
     locale: Locale = .en,
-    type: ContentType? = nil,
+    type: ContentType = .website,
     themeColor: ThemeColor? = nil
   ) {
     self.site = site
@@ -105,7 +105,7 @@ extension Metadata {
   ///   - type: Optional content type, default is the same as `base`.
   ///   - themeColor: Optional theme color, default is the same as `base`.
   public init(
-    base: Metadata,
+    from base: Metadata,
     site: String? = nil,
     title: String? = nil,
     titleSeperator: String? = nil,

Sources/WebUI/Elements/Base/Media.swift

@@ -64,23 +64,30 @@ public final class Source: Element {
 
 /// Generates an HTML img element.
 public final class Image: Element {
+  let source: String
   let description: String
   let size: MediaSize?
 
   /// Creates a new HTML img element.
   ///
   /// - Parameters:
+  ///   - source: Where the image is located.
   ///   - description: Alt text for accessibility.
   ///   - size: Image size dimensions, optional.
   ///   - data: Dictionary of `data-*` attributes for element relevant storing data.
   public init(
+    source: String,
     description: String,
     size: MediaSize? = nil,
     data: [String: String]? = nil
   ) {
+    self.source = source
     self.description = description
     self.size = size
     var customAttributes: [String] = []
+    if !source.isEmpty {
+      customAttributes.append("src=\"\(source)\"")
+    }
     if !description.isEmpty {
       customAttributes.append("alt=\"\(description)\"")
     }
@@ -140,7 +147,7 @@ public final class Picture: Element {
         for source in sources {
           Source(src: source.src, type: source.type?.rawValue)
         }
-        Image(description: description, size: size)
+        Image(source: sources[0].src, description: description, size: size)
       }
     )
   }

Sources/WebUI/HTML/Children.swift

@@ -0,0 +1,14 @@
+/// Represents a collection of HTML children, built declaratively.
+public struct Children {
+  private let content: [any HTML]
+
+  /// Initializes children using an HTMLBuilder closure.
+  public init(@HTMLBuilder content: HTMLContentBuilder) {
+    self.content = content()
+  }
+
+  /// Renders all children as a single HTML string.
+  public func render() -> String {
+    content.map { $0.render() }.joined()
+  }
+}

Sources/WebUI/HTML/HTMLBuilder.swift

@@ -69,3 +69,6 @@ public struct HTMLBuilder {
     components.flatMap { $0 }
   }
 }
+
+/// Type alias for a closure that builds HTML content.
+public typealias HTMLContentBuilder = () -> [any HTML]

Sources/WebUI/Styles/Appearance/Border.swift

@@ -92,7 +92,6 @@ extension Element {
   public func border(
     width: Int? = nil,
     edges: Edge...,
-    radius: (side: RadiusSide?, size: RadiusSize)? = nil,
     style: BorderStyle? = nil,
     color: Color? = nil,
     on modifiers: Modifier...
@@ -104,7 +103,8 @@ extension Element {
     if let width = width {
       if style == .divide {
         for edge in effectiveEdges {
-          let edgePrefix = edge == .horizontal ? "x" : edge == .vertical ? "y" : ""
+          let edgePrefix =
+            edge == .horizontal ? "x" : edge == .vertical ? "y" : ""
           if !edgePrefix.isEmpty {
             baseClasses.append("divide-\(edgePrefix)-\(width)")
           }
@@ -114,7 +114,8 @@ extension Element {
           contentsOf: effectiveEdges.map { edge in
             let edgePrefix = edge.rawValue.isEmpty ? "" : "-\(edge.rawValue)"
             return "border\(edgePrefix)\(width != 0 ? "-\(width)" : "")"
-          })
+          }
+        )
       }
     }
 
@@ -124,14 +125,8 @@ extension Element {
         contentsOf: effectiveEdges.map { edge in
           let edgePrefix = edge.rawValue.isEmpty ? "" : "-\(edge.rawValue)"
           return "border\(edgePrefix)"
-        })
-    }
-
-    // Handle radius
-    if let (side, size) = radius {
-      let sidePrefix = side?.rawValue ?? ""
-      let sideClass = sidePrefix.isEmpty ? "" : "-\(sidePrefix)"
-      baseClasses.append("rounded\(sideClass)-\(size.rawValue)")
+        }
+      )
     }
 
     // Handle style
@@ -140,7 +135,8 @@ extension Element {
         contentsOf: effectiveEdges.map { edge in
           let edgePrefix = edge.rawValue.isEmpty ? "" : "-\(edge.rawValue)"
           return "border\(edgePrefix)-\(styleValue.rawValue)"
-        })
+        }
+      )
     }
 
     // Handle color
@@ -162,6 +158,27 @@ extension Element {
     )
   }
 
+  public func rounded(
+    _ size: RadiusSize,
+    _ edge: RadiusSide = .all,
+    on modifiers: Modifier...
+  ) -> Element {
+    let sidePrefix = edge.rawValue.isEmpty ? "" : "-\(edge.rawValue)"
+    let baseClasses = ["rounded\(sidePrefix)-\(size.rawValue)"]
+    let newClasses = combineClasses(baseClasses, withModifiers: modifiers)
+
+    return Element(
+      tag: self.tag,
+      id: self.id,
+      classes: (self.classes ?? []) + newClasses,
+      role: self.role,
+      label: self.label,
+      isSelfClosing: self.isSelfClosing,
+      customAttributes: self.customAttributes,
+      content: self.contentBuilder
+    )
+  }
+
   public func outline(
     width: Int? = nil,
     style: BorderStyle? = nil,

Sources/WebUI/Utilities/String.swift

@@ -11,7 +11,7 @@ extension String: HTML {
 
   /// Converts the string to a lowercase, hyphen-separated path representation.
   public func pathFormatted() -> String {
-    lowercased()
+    self.lowercased()
       .replacingOccurrences(of: "[^a-z0-9 ]", with: "", options: .regularExpression)
       .split(separator: " ")
       .filter { !$0.isEmpty }

Tests/WebUITests/Core/DocumentTests.swift

@@ -77,17 +77,17 @@ import Testing
         description: "Testing script inclusion"
       ),
       scripts: [
-        "https://cdn.example.com/script1.js",
-        "/public/script2.js",
+        "https://cdn.example.com/script1.js": .async,
+        "/public/script2.js": .defer,
       ]
     ) {
       "Script Test"
     }.render()
 
     #expect(
       rendered.contains(
-        "<script src=\"https://cdn.example.com/script1.js\"></script>"))
-    #expect(rendered.contains("<script src=\"/public/script2.js\"></script>"))
+        "<script async src=\"https://cdn.example.com/script1.js\"></script>"))
+    #expect(rendered.contains("<script defer src=\"/public/script2.js\"></script>"))
   }
 
   /// Tests that custom stylesheets are correctly added to the document head.

Tests/WebUITests/Styles/AppearanceTests.swift

@@ -67,10 +67,17 @@ import Testing
 
   @Test("Border with radius")
   func testBorderWithRadius() async throws {
-    let element = Element(tag: "div").border(radius: (.all, .md))
+    let element = Element(tag: "div").rounded(.md)
     let rendered = element.render()
     #expect(rendered.contains("class=\"rounded-md\""))
   }
+  
+  @Test("Border with radius on just one side")
+  func testBorderWithOneSidedRadius() async throws {
+    let element = Element(tag: "div").rounded(.full, .topLeft)
+    let rendered = element.render()
+    #expect(rendered.contains("class=\"rounded-tl-full\""))
+  }
 
   @Test("Border with specific edge and color")
   func testBorderWithEdgeAndColor() async throws {