added HTMX SSE; some README touchups

RandomHashTags · RandomHashTags · commit 8f9a3f124d60 · 2024-11-14T18:10:00.000-06:00
diff --git a/README.md b/README.md
@@ -24,7 +24,20 @@ Write HTML using Swift Macros. Supports HTMX via global attributes.
 <details>
 <summary>How do I use this library?</summary>
 
-Syntax: `#<html element>(attributes: [], <element specific attributes>: V?, _ innerHTML: ExpressibleByStringLiteral...)`
+#### Syntax
+
+```swift
+
+#<html element>(
+  attributes: [<global attribute>],
+  <element specific attribute>: <element specific attribute value>?,
+  _ innerHTML: ExpressibleByStringLiteral...
+)
+
+```
+
+- all parameters are optional by default
+
 #### Examples
 
 ```swift
@@ -104,20 +117,26 @@ Using String Interpolation.
 
 > You will get a compiler warning saying *interpolation may introduce raw HTML*.
 > 
-> Its up to you whether or not to suppress this warning or escape the HTML at runtime using an method described above.
+> Its up to you whether or not to suppress this warning or escape the HTML at runtime using a method described above.
 > 
 > Swift HTMLKit tries to [replace](https://github.com/RandomHashTags/swift-htmlkit/blob/94793984763308ef5275dd9f71ea0b5e83fea417/Sources/HTMLKitMacros/HTMLElement.swift#L423) known interpolation at compile time with a compile time equivalent for the best performance. It is currently limited due to macro expansions being sandboxed and lexical contexts/AST not being available for macro arguments. This means referencing content known at compile time in a html macro won't get replaced by its literal contents. [Read more about this limitation](https://forums.swift.org/t/swift-lexical-lookup-for-referenced-stuff-located-outside-scope-current-file/75776/6).
 
 #### Example
 ```swift
 let string:String = "any string value", integer:Int = -69, float:Float = 3.141592
 
+// ✅ DO
 let _:String = #p("\(string); \(integer); \(float)")
 let _:String = #p("\(string)", "; ", String(describing: integer), "; ", float.description)
-// the below also works
+
 let integer_string:String = String(describing: integer), float_string:String = String(describing: float)
 let _:String = #p(string, "; ", integer_string, "; ", float_string)
 
+// ❌ DON'T; compiler error; compile time value cannot contain interpolation
+let _:StaticString = #p("\(string); \(integer); \(float)")
+let _:StaticString = #p("\(string)", "; ", String(describing: integer), "; ", float.description)
+let _:StaticString = #p(string, "; ", integer_string, "; ", float_string)
+
 ```
 
 </details>
@@ -194,7 +213,7 @@ Use a different html macro. Currently supported types (more to come with new lan
 
 <summary>How do I use HTMX?</summary>
 
-Use the `.htmx(<htmx attribute>)` global attribute. All HTMX 2.0 attributes are supported (including web socket).
+Use the `.htmx(<htmx attribute>)` global attribute. All HTMX 2.0 attributes are supported (including Server Sent Events & Web Sockets).
 
 #### Examples
 ```swift
@@ -217,6 +236,9 @@ string = #div(attributes: [.htmx(.onevent(.click, "thing()"))])
 // <div hx-preserve></div>
 string = #div(attributes: [.htmx(.preserve(true))])
 
+// <div sse-connect="/connect"></div>
+string = #div(attributes: [.htmx(.sse(.connect("/connect")))])
+
 // <div ws-connect="/chatroom"></div>
 string = #div(attributes: [.htmx(.ws(.connect("/chatroom")))])
 
diff --git a/Sources/HTMLKitMacros/HTMLElement.swift b/Sources/HTMLKitMacros/HTMLElement.swift
@@ -202,6 +202,9 @@ private extension HTMLElement {
                                     case .request(_, _, _, _), .headers(_, _):
                                         delimiter = "'"
                                         break
+                                    case .sse(let sse_value):
+                                        key = "sse-" + sse_value.key
+                                        break
                                     case .ws(let ws_value):
                                         key = "ws-" + ws_value.key
                                         switch ws_value {
diff --git a/Sources/HTMLKitUtilities/HTMX.swift b/Sources/HTMLKitUtilities/HTMX.swift
@@ -44,6 +44,7 @@ public extension HTMLElementAttribute {
         case trigger(String)
         case vals(String)
 
+        case sse(ServerSentEvents)
         case ws(WebSocket)
 
         public init?(rawValue: String) {
@@ -182,6 +183,7 @@ public extension HTMLElementAttribute {
                 case "trigger": self = .trigger(string())
                 case "vals": self = .vals(string())
 
+                case "sse": self = .sse(ServerSentEvents(rawValue: literal())!)
                 case "ws": self = .ws(WebSocket(rawValue: literal())!)
                 default: return nil
             }
@@ -226,6 +228,7 @@ public extension HTMLElementAttribute {
                 case .trigger(_): return "trigger"
                 case .vals(_): return "vals"
 
+                case .sse(let event): return "sse-" + event.key
                 case .ws(let value): return "ws-" + value.key
             }
         }
@@ -280,6 +283,7 @@ public extension HTMLElementAttribute {
                 case .trigger(let value): return value
                 case .vals(let value): return value
 
+                case .sse(let value): return value.htmlValue
                 case .ws(let value): return value.htmlValue
             }
         }
@@ -506,6 +510,47 @@ public extension HTMLElementAttribute.HTMX {
     }
 }
 
+// MARK: Server Sent Events
+public extension HTMLElementAttribute.HTMX {
+    enum ServerSentEvents {
+        case connect(String)
+        case swap(String)
+        case close(String)
+
+        public init?(rawValue: String) {
+            guard rawValue.last == ")" else { return nil }
+            let start:String.Index = rawValue.startIndex, end:String.Index = rawValue.index(before: rawValue.endIndex), end_minus_one:String.Index = rawValue.index(before: end)
+            let key:Substring = rawValue.split(separator: "(")[0]
+            func string() -> String {
+                return String(rawValue[rawValue.index(start, offsetBy: key.count + 2)..<end_minus_one])
+            }
+            switch key {
+                case "connect": self = .connect(string())
+                case "swap": self = .swap(string())
+                case "close": self = .close(string())
+                default: return nil
+            }
+        }
+
+        public var key : String {
+            switch self {
+                case .connect(_): return "connect"
+                case .swap(_): return "swap"
+                case .close(_): return "close"
+            }
+        }
+
+        public var htmlValue : String {
+            switch self {
+                case .connect(let value),
+                        .swap(let value),
+                        .close(let value):
+                    return value
+            }
+        }
+    }
+}
+
 // MARK: WebSocket
 public extension HTMLElementAttribute.HTMX {
     enum WebSocket {
diff --git a/Tests/HTMLKitTests/HTMXTests.swift b/Tests/HTMLKitTests/HTMXTests.swift
@@ -154,6 +154,24 @@ struct HTMXTests {
         #expect(string == "<div hx-sync=\"#submit-button:queue first\"></div>")
     }
 
+    // MARK: sse
+    @Test func sse() {
+        var string:StaticString = #div(attributes: [.htmx(.sse(.connect("/connect")))])
+        #expect(string == "<div sse-connect=\"/connect\"></div>")
+
+        string = #div(attributes: [.htmx(.sse(.swap("message")))])
+        #expect(string == "<div sse-swap=\"message\"></div>")
+
+        string = #div(attributes: [.htmx(.sse(.close("message")))])
+        #expect(string == "<div sse-close=\"message\"></div>")
+    }
+
+    // MARK: trigger
+    @Test func trigger() {
+        let string:StaticString = #div(attributes: [.htmx(.trigger("sse:chatter"))])
+        #expect(string == "<div hx-trigger=\"sse:chatter\"></div>")
+    }
+
     // MARK: ws
     @Test func ws() {
         var string:StaticString = #div(attributes: [.htmx(.ws(.connect("/chatroom")))])
