feat: add event handling to swift bindings

- Allow registering callbacks to be invoked when document changes
- Add some documentation to the public APIs

Author: bitwalker

swift/LiveViewNative/Sources/LiveViewNative/LiveViewNative.swift

@@ -1,5 +1,6 @@
 import LiveViewNativeCore
 
+/// Raised when a `Document` fails to parse
 public struct ParseError: Error {
     let message: String
 
@@ -8,8 +9,26 @@ public struct ParseError: Error {
     }
 }
 
+/// Represents the various types of events that a `Document` can produce
+public enum EventType {
+    /// When a document is modified in some way, the `changed` event is raised
+    case changed
+}
+
+struct Handler {
+    let context: AnyObject?
+    let callback: (Document, AnyObject?) -> ()
+
+    func call(_ doc: Document) {
+        callback(doc, context)
+    }
+}
+
+/// A `Document` corresponds to the tree of elements in a UI, and supports a variety
+/// of operations used to traverse, query, and mutate that tree.
 public class Document {
     var repr: __Document
+    var handlers: [EventType: Handler] = [:]
 
     init(_ doc: __Document) {
         self.repr = doc
@@ -18,9 +37,19 @@ public class Document {
     deinit {
         __liveview_native_core$Document$drop(self.repr)
     }
-}
 
-extension Document {
+    /// Parse a `Document` from the given `String` or `String`-like type
+    ///
+    /// The given text should be a valid HTML-ish document, insofar that the structure should
+    /// be that of an HTML document, but the tags, attributes, and their usages do not have to
+    /// be valid according to the HTML spec.
+    ///
+    /// - Parameters:
+    ///   - str: The string to parse
+    ///
+    /// - Returns: A document representing the parsed content
+    ///
+    /// - Throws: `ParseError` if the content cannot be parsed for some reason
     public static func parse<S: ToRustStr>(_ str: S) throws -> Document {
         try str.toRustStr({ rustStr -> Result<Document, ParseError> in
             let errorPtr = UnsafeMutableRawPointer.allocate(byteCount: MemoryLayout<_RustString>.stride, alignment: MemoryLayout<_RustString>.alignment).assumingMemoryBound(to: _RustString.self)
@@ -36,14 +65,44 @@ extension Document {
                       }).get()
     }
 
-    public func merge(with doc: Document) -> Bool {
-        return __liveview_native_core$Document$merge(self.repr, doc.repr)
+    /// Register a callback to be fired when a matching event occurs on this document.
+    ///
+    /// The given callback receives the document to which the event applies, as well as the
+    /// (optional) context object provided.
+    ///
+    /// Only one callback per event type is supported. Calling this function multiple times for the
+    /// same event will only result in the last callback provided being invoked for that tevent
+    ///
+    /// - Parameters:
+    ///   - event: The `EventType` for which the given callback should be invoked
+    ///   - context: A caller-provided value which should be passed to the callback when it is invoked
+    ///   - callback: The callback to invoke when an event of the given type occurs
+    ///
+    public func on(_ event: EventType, with context: AnyObject?, _ callback: @escaping (Document, AnyObject?) -> ()) {
+        self.handlers[event] = Handler(context: context, callback: callback)
+    }
+
+    /// Updates this document by calculating the changes needed to make it equivalent to `doc`,
+    /// and then applying those changes.
+    ///
+    /// - Parameters:
+    ///   - doc: The document to compare against
+    public func merge(with doc: Document) {
+        if __liveview_native_core$Document$merge(self.repr, doc.repr) {
+            if let handler = self.handlers[.changed] {
+                handler.call(self)
+            }
+        }
     }
 
+    /// Returns a reference to the root node of the document
+    ///
+    /// The root node is not part of the document itself, but can be used to traverse the document tree top-to-bottom.
     public func root() -> NodeRef {
         return __liveview_native_core$Document$root(self.repr)
     }
 
+    /// Enables indexing of the document by node reference, returning the reified `Node` to which it corresponds
     public subscript(ref: NodeRef) -> Node {
         let node = __liveview_native_core$Document$get(self.repr, ref)
         return Node(doc: self, ref: ref, data: node)
@@ -65,16 +124,33 @@ extension Document {
     }
 }
 
+/// Represents a node in the document tree
+///
+/// A node can be one of three types:
+///
+/// - A root node, which is a special marker node for the root of the document
+/// - A leaf node, which is simply text content, cannot have children or attributes
+/// - An element node, which can have children and attributes
+///
+/// A node in a document is uniquely identified by a `NodeRef` for the lifetime of
+/// that node in the document. But a `NodeRef` is not a stable identifier when the
+/// tree is modified. In some cases the `NodeRef` remains the same while the content
+/// changes, and in others, a new node is allocated, so a new `NodeRef` is used.
 public class Node: Identifiable {
+    /// The type and associated data of this node
     public enum Data {
-        case Root
-        case Element(HTMLElement)
-        case Leaf(String)
+        case root
+        case element(ElementNode)
+        case leaf(String)
     }
 
     let doc: Document
+
+    /// The identifier for this node in its `Document`
     public let id: NodeRef
+    /// The type and data associated with this node
     public let data: Data
+    /// The attributes associated with this node
     public lazy var attributes: [Attribute] = {
         let refs = doc.getAttrs(id)
         var attributes: [Attribute] = []
@@ -89,14 +165,15 @@ public class Node: Identifiable {
         self.doc = doc
         switch data.ty {
         case .NodeTypeRoot:
-            self.data = .Root
+            self.data = .root
         case .NodeTypeElement:
-            self.data = .Element(HTMLElement(doc: doc, ref: ref, data: data.data.element))
+            self.data = .element(ElementNode(doc: doc, ref: ref, data: data.data.element))
         case .NodeTypeLeaf:
-            self.data = .Leaf(RustStr(data.data.leaf).toString()!)
+            self.data = .leaf(RustStr(data.data.leaf).toString()!)
         }
     }
 
+    /// Nodes are indexable by attribute name, returning the first attribute with that name
     public subscript(_ name: AttributeName) -> Attribute? {
         for attr in attributes {
             if attr.name == name {
@@ -113,6 +190,7 @@ extension Node: Sequence {
     }
 }
 
+/// An iterator for the direct children of a `Node`
 public struct NodeChildrenIterator: IteratorProtocol {
     let doc: Document
     let children: RustSlice<NodeRef>
@@ -133,9 +211,13 @@ public struct NodeChildrenIterator: IteratorProtocol {
     }
 }
 
-public struct HTMLElement {
+/// Represents a node in a `Document` which can have children and attributes
+public struct ElementNode {
+    /// An (optional) namespace for the element tag name
     public let namespace: String?
+    /// The name of the element tag in the document
     public let tag: String
+    /// A dictionary of attributes associated with this element
     public let attributes: [AttributeName: String]
 
     init(doc: Document, ref: NodeRef, data: __Element) {
@@ -151,8 +233,11 @@ public struct HTMLElement {
     }
 }
 
+/// An attribute is a named string value associated with an element
 public struct Attribute {
+    /// The fully-qualified name of the attribute
     public var name: AttributeName
+    /// The value of this attribute, if there was one
     public var value: String?
 
     init(name: AttributeName, value: String?) {
@@ -183,6 +268,10 @@ extension Attribute: Hashable {
     }
 }
 
+/// Represents a fully-qualified attribute name
+///
+/// Attribute names can be namespaced, so rather than represent them as a plain `String`,
+/// we use this type to preserve the information for easy accessibility.
 public struct AttributeName {
     public var namespace: String?
     public var name: String