LiveViewNative SwiftUI

LiveViewNative uses a hierarchical coordination model to map Phoenix LiveView server-side state to SwiftUI views. The architecture follows this flow:

1. LiveView: The entry point SwiftUI View that initiates the connection.
2. LiveSessionCoordinator: Manages the single WebSocket connection for the entire LiveView session.
3. LiveViewCoordinator: Manages individual Phoenix Channels. As the server performs navigation (via push_event, push_patch, or redirect), the LiveSessionCoordinator spawns or manages multiple LiveViewCoordinator instances, each representing a route in the navigation stack.
4. NavStackEntryView: The actual SwiftUI view hierarchy that renders the content received for a specific route.

This design allows for complex layouts, such as a sidebar/content/detail split, where different parts of the screen can render different Phoenix LiveViews simultaneously over the same shared WebSocket connection.

The StylesheetResolvable protocol allows you to decode SwiftUI primitives (like HorizontalAlignment or ShapeStyle) that need to be resolved from a stylesheet.

Many SwiftUI types have a nested .Resolvable type. You can use these in your modifiers to allow dynamic values in stylesheets.

Examples:

1. Using built-in SwiftUI types (e.g., HorizontalAlignment):

struct MyModifier<Root: RootRegistry>: ViewModifier, Decodable {
    let alignment: HorizontalAlignment.Resolvable

    func body(content: Content) -> some View {
        VStack(alignment: alignment.resolve(on: element, in: context)) { content }
    }
}

Stylesheet: myModifier(alignment: .trailing)

2. Using specialized protocols (e.g., ShapeStyle): Use StylesheetResolvableShapeStyle to decode a type-erased ShapeStyle.

struct FillBackgroundModifier<Root: RootRegistry>: ViewModifier, @preconcurrency Decodable {
    let fill: StylesheetResolvableShapeStyle

    init(_ fill: StylesheetResolvableShapeStyle) {
        self.fill = fill
    }
    
    func body(content: Content) -> some View {
        content.background(fill)
    }
}

Stylesheet: fillBackground(.red.opacity(attr("opacity")))

3. Creating custom resolvable types: Conform your own struct to StylesheetResolvable to allow its properties to use attr(<name>).

struct Video {
    let url: String
    let resolution: Int

    struct Resolvable: StylesheetResolvable, Decodable {
        let url: AttributeReference<String>
        let resolution: AttributeReference<Int>

        func resolve(on element: ElementNode, in context: LiveContext<some RootRegistry>) -> Video {
            Video(
                url: url.resolve(on: element, in: context),
                resolution: resolution.resolve(on: element, in: context)
            )
        }
    }
}

Stylesheet: backgroundVideo(Video("...", in: attr("resolution")))

@ASTDecodable("fillBackground")
struct FillBackgroundModifier<Root: RootRegistry>: ViewModifier, @preconcurrency Decodable {
    let fill: StylesheetResolvableShapeStyle

    init(_ fill: StylesheetResolvableShapeStyle) {
        self.fill = fill
    }
    
    func body(content: Content) -> some View {
        content.background(fill)
    }
}

In LiveViewNative, you apply changes to elements using either Attributes or Modifiers. Choosing the right one depends on the scope of the change you want to apply.

Attributes

• Scope: Apply to a single, specific element.
• Implementation: Implemented directly on specific view types (e.g., placeholder on <doc:TextField>).
• Data Format: Stores a single string value.
• Use Case: Use attributes when a property is unique to a specific element type.

Modifiers

• Scope: Apply to a large swath of elements or broad categories of elements.
• Implementation: Implemented separately from view types; they cannot directly access or manipulate specific views.
• Data Format: Stored as JSON objects within a JSON array on the modifiers attribute of an element. This array structure allows for order-dependent composition.
• Capabilities: Can hold multiple related values (e.g., distinct values for different edges of a padding modifier).
• Use Case: Use modifiers when you want to reuse changes across many elements or apply a consistent style to a category of views.