Update documentation

Author: carson-katri

README.md

@@ -9,17 +9,15 @@ The LiveViewNative Swift package lets you use Phoenix LiveView to build native i
 3. Select *Add Package*
 
 ## Usage
-Create a `LiveSessionCoordinator` and pass in the URL to your Phoenix server. Then use `LiveView` to connect to that session.
+Create a `LiveView` to connect to a Phoenix server running on `http://localhost:4000`.
 
 ```swift
 import SwiftUI
 import LiveViewNative
 
 struct ContentView: View {
-    @StateObject private var session = LiveSessionCoordinator(URL(string: "http://localhost:4000")!)
-
     var body: some View {
-        LiveView(session: session)
+        LiveView(.localhost)
     }
 }
 ```

Sources/LiveViewNative/LiveViewHost.swift

@@ -8,23 +8,69 @@
 import Foundation
 
 /// The information needed to locate a server hosting a LiveView.
+///
+/// This protocol gives quick access to common LiveView hosts.
+///
+/// For example, use ``LocalhostLiveViewHost/localhost`` to quickly connect to a development server on port `4000`.
+///
+/// - Note: You can use ``LocalhostLiveViewHost/localhost(port:path:)`` to customize the port and base path of your Phoenix server.
+///
+/// ```swift
+/// struct ContentView: View {
+///     var body: some View {
+///         LiveView(.localhost)
+///     }
+/// }
+/// ```
+///
+/// To provide a custom `URL`, use ``CustomLiveViewHost/custom(_:)``.
+///
+/// - Note: In many cases, it is easier to use ``LiveView/init(url:configuration:)`` to provide a custom URL.
+///
+/// ```swift
+/// struct ContentView: View {
+///     var body: some View {
+///         LiveView(URL(string: "https://example.com")!)
+///     }
+/// }
+/// ```
+///
+/// ## Switching Between Development/Production
+/// In many cases, a different host should be used for development and production environments.
+///
+/// Use ``AutomaticLiveViewHost/automatic(_:)`` or ``AutomaticLiveViewHost/automatic(development:production:)`` to easily switch hosts based on the `DEBUG` compiler directive.
+///
+/// - Note: `DEBUG` is setup by default in new Xcode projects for the debug configuration.
+///
+/// ```swift
+/// struct ContentView: View {
+///     var body: some View {
+///         LiveView(.automatic(URL(string: "https://example.com")!))
+///     }
+/// }
+/// ```
 public protocol LiveViewHost {
     var url: URL { get }
 }
 
 public struct LocalhostLiveViewHost: LiveViewHost {
     public let url: URL
 
-    init(port: Int) {
-        self.url = .init(string: "http://localhost:\(port)")!
+    init(port: Int = 4000, path: String? = nil) {
+        let base = URL(string: "http://localhost:\(port)")!
+        if let path {
+            self.url = base.appending(path: path)
+        } else {
+            self.url = base
+        }
     }
 }
 
 public extension LiveViewHost where Self == LocalhostLiveViewHost {
     /// A server at `http://localhost:4000`.
-    static var localhost: Self { .init(port: 4000) }
-    /// A server at `localhost` on the given port.
-    static func localhost(port: Int) -> Self { .init(port: port) }
+    static var localhost: Self { .init() }
+    /// A server at `localhost` on the given port with a custom base path.
+    static func localhost(port: Int = 4000, path: String? = nil) -> Self { .init(port: port, path: path) }
 }
 
 public struct CustomLiveViewHost: LiveViewHost {
@@ -62,6 +108,8 @@ public extension LiveViewHost where Self == AutomaticLiveViewHost {
     }
 
     /// Automatically select a host based on the `DEBUG` compiler directive.
+    ///
+    /// Provide the `URL` of the production host. The development host defaults to ``LocalhostLiveViewHost/localhost``.
     static func automatic(_ url: URL) -> Self {
         .init(development: .localhost, production: .custom(url))
     }

Sources/LiveViewNative/LiveViewNative.docc/GettingStarted.md

@@ -4,30 +4,22 @@ See how to quickly get up and running displaying a LiveView in your app.
 
 ## First Steps
 
-Getting started with LiveViewNative is easy: simply create a ``LiveSessionCoordinator`` and pass it into a ``LiveView`` that's part of your view tree.
+Getting started with LiveViewNative is easy: simply use a ``LiveView`` as part of your view tree, and pass a ``LiveViewHost`` to launch.
 
-The coordinator object is responsible for connecting to the Phoenix LiveView backend, managing the network connection, and sending and responding to events.
-
-Only one coordinator may be used for a view, so use `@State` to store it on the containing view.
-
-The only information you are required to provide is the URL of the live view to connect to.
-
-The LiveView is then created by passing in the coordinator, no other setup necessary.
+This can be ``LocalhostLiveViewHost/localhost``, some other ``AutomaticLiveViewHost/automatic(development:production:)``, or any `URL` with ``LiveView/init(url:configuration:)``.
 
 ```swift
 @MainActor
 struct ContentView: View {
-    @State private var session = LiveSessionCoordinator(URL(string: "http://localhost:4000/")!)
-
     var body: some View {
-        LiveView(session: session)
+        LiveView(.localhost)
     }
 }
 ```
 
-## Configuring the Coordinator
+## Configuring the LiveView
 
-The coordinator can be configured with a number of different options. To customize these, create a ``LiveSessionConfiguration`` with the values you want, and then pass it to coordinator's initializer.
+The ``LiveView`` can be configured with a number of different options. To customize these, create a ``LiveSessionConfiguration`` with the values you want, and then pass it to view's initializer.
 
 ```swift
 @MainActor
@@ -39,22 +31,41 @@ struct ContentView: View {
     }()
 
     var body: some View {
-        LiveView(session: session)
+        LiveView(
+            .localhost,
+            configuration: LiveSessionConfiguration(navigationMode: .enabled)
+        )
     }
 }
 ```
 
 ## Supporting Custom Elements
 
-You can enable support for your own custom HTML elements and attributes by implementing the ``CustomRegistry`` protocol and providing it to the coordinator. The protocol uses only static methods, so rather than constructing an instance of your registry, you provide it as a generic type to the coordinator when constructing it:
+You can enable support for your own custom HTML elements and attributes by implementing the ``CustomRegistry`` protocol and providing it to the coordinator. The protocol uses only static methods, so rather than constructing an instance of your registry, you provide it as a generic type to the ``LiveView`` when constructing it:
 
 ```swift
 @MainActor
 struct ContentView: View {
-    @State private var session = LiveSessionCoordinator<MyCustomRegistry>(URL(string: "http://localhost:4000/")!)
+    var body: some View {
+        LiveView<MyCustomRegistry>(.localhost)
+    }
+}
+```
+
+## Accessing the ``LiveSessionCoordinator``
+
+``LiveSessionCoordinator`` handles everything needed to connect and run a ``LiveView``. When you pass a ``LiveViewHost`` or `URL` in the initializer, this coordinator is created for you.
+
+However, in some cases you may want access to this coordinator to send or receive custom events. In these cases, create the ``LiveSessionCoordinator`` yourself, and pass it to ``LiveView/init(session:)``.
+
+```swift
+struct ContentView: View {
+    @StateObject private var session = LiveSessionCoordinator<MyCustomRegistry>(.localhost)
 
     var body: some View {
         LiveView(session: session)
     }
 }
 ```
+
+Now you have full access to the ``LiveSessionCoordinator`` and all of its properties and methods.

Sources/LiveViewNative/LiveViewNative.docc/LiveViewNative.md

@@ -13,17 +13,15 @@ The LiveViewNative Swift package lets you use Phoenix LiveView to build native i
 3. Select *Add Package*
 
 ## Usage
-Create a `LiveSessionCoordinator` and pass in the URL to your Phoenix server. Then use `LiveView` to connect to that session.
+Create a `LiveView` and pass in a ``LiveViewHost`` or the `URL` to your Phoenix server.
 
 ```swift
 import SwiftUI
 import LiveViewNative
 
 struct ContentView: View {
-    @StateObject private var session = LiveSessionCoordinator(URL(string: "http://localhost:4000")!)
-
     var body: some View {
-        LiveView(session: session)
+        LiveView(.localhost)
     }
 }
 ```

Sources/LiveViewNative/LiveViewNative.docc/Resources/01-02-06-session.swift

@@ -3,8 +3,6 @@ import LiveViewNative
 
 @MainActor
 struct ContentView: View {
-    @StateObject private var session = LiveSessionCoordinator(URL(string: "http://localhost:4000/cats")!)
-
     var body: some View {
         VStack {
             Image(systemName: "globe")

Sources/LiveViewNative/LiveViewNative.docc/Resources/01-02-07-liveview.swift

@@ -3,9 +3,7 @@ import LiveViewNative
 
 @MainActor
 struct ContentView: View {
-    @StateObject private var session = LiveSessionCoordinator(URL(string: "http://localhost:4000/cats")!)
-
     var body: some View {
-        LiveView(session: session)
+        LiveView(.localhost(path: "cats"))
     }
 }

Sources/LiveViewNative/LiveViewNative.docc/Resources/03-02-01-navigationmode.swift

@@ -3,13 +3,10 @@ import LiveViewNative
 
 @MainActor
 struct ContentView: View {
-    @StateObject private var session: LiveSessionCoordinator<EmptyRegistry> = {
-        var config = LiveSessionConfiguration()
-        config.navigationMode = .enabled
-        return LiveSessionCoordinator(URL(string: "http://localhost:4000/cats")!, config: config)
-    }()
-
     var body: some View {
-        LiveView(session: session)
+        LiveView(
+            .localhost(path: "cats"),
+            configuration: LiveSessionConfiguration(navigationMode: .enabled)
+        )
     }
 }

Sources/LiveViewNative/LiveViewNative.docc/Resources/04-01-04-session.swift

@@ -3,13 +3,10 @@ import LiveViewNative
 
 @MainActor
 struct ContentView: View {
-    @StateObject private var session: LiveSessionCoordinator<MyRegistry> = {
-        var config = LiveSessionConfiguration()
-        config.navigationMode = .enabled
-        return LiveSessionCoordinator(URL(string: "http://localhost:4000/cats")!, config: config)
-    }()
-
     var body: some View {
-        LiveView(session: session)
+        LiveView<MyRegistry>(
+            .localhost(path: "cats"),
+            configuration: LiveSessionConfiguration(navigationMode: .enabled)
+        )
     }
 }

Sources/LiveViewNative/LiveViewNative.docc/Tutorials/01 Initial List.tutorial

@@ -165,9 +165,7 @@
             }
 
             @Step {
-                Then, import the LiveViewNative package and add the session as a `@StateObject` variable, using the URL of your Phoenix project.
-                
-                The coordinator handles all networking for the LiveView, and so only one instance of it should exist. We use a `@State` variable for this so that the coordinator isn't re-created if SwiftUI re-creates the containing view.
+                Then, import the LiveViewNative package at the top of the file.
 
                 @Comment {
                     project = "app"
@@ -177,7 +175,7 @@
             }
 
             @Step {
-                Lastly, add the `LiveView` to your view's body, passing in the coordinator.
+                Lastly, add the `LiveView` to your view's body, passing in ``LocalhostLiveViewHost/localhost(port:path:)`` as the host with a custom base path.
 
                 Then, you can run the app in the Simulator and see it connecting to your Phoenix app. Make sure you've started the Phoenix server with `mix phx.server`!