@swiftbrowser/native 0.0.0-stage → 0.10.1

package/swift/Sources/SwiftBrowserProtocol/Props.swift

@@ -0,0 +1,469 @@
+import Foundation
+
+// Typed readers over an element's props, one per kind a renderer draws
+// (docs/ops-protocol.md, "Element kinds and props"). Each reads the fields
+// the protocol defines with the protocol's defaults, from the JSON the tree
+// keeps; `init(props:)` never fails, since a renderer draws what it can.
+
+public struct TextProps: Equatable, Sendable {
+    public var text: String
+    /// Rich text (`runs`), when the text has styled runs; empty for plain text.
+    public var runs: [TextRunSpec]
+
+    public init(props: JSONObject) {
+        text = props.string("text") ?? ""
+        runs = (props.array("runs") ?? []).compactMap(TextRunSpec.init(json:))
+    }
+}
+
+/// One run of a rich `text`: its text or inline image, and the attributes over the text's own.
+public struct TextRunSpec: Equatable, Sendable {
+    public var text: String?
+    public var image: ImageProps?
+    public var font: FontSpec?
+    public var foreground: ShapeStyleSpec?
+    public var italic: Bool
+    public var underline: Bool
+    public var underlineColor: ColorSpec?
+    public var strikethrough: Bool
+    public var strikethroughColor: ColorSpec?
+    public var kerning: Double?
+    public var baselineOffset: Double?
+    public var link: String?
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        text = fields.string("text")
+        image = fields.object("image").map(ImageProps.init(props:))
+        font = FontSpec(json: fields.value("font"))
+        foreground = ShapeStyleSpec(json: fields.value("foreground"))
+        italic = fields.bool("italic") ?? false
+        underline = fields["underline"] != nil
+        underlineColor = ColorSpec(json: fields.value("underline")["color"])
+        strikethrough = fields["strikethrough"] != nil
+        strikethroughColor = ColorSpec(json: fields.value("strikethrough")["color"])
+        kerning = fields.double("kerning")
+        baselineOffset = fields.double("baselineOffset")
+        link = fields.string("link")
+    }
+}
+
+public struct StackProps: Equatable, Sendable {
+    /// Nil is the system default spacing.
+    public var spacing: Double?
+    /// A `VStack`'s horizontal alignment, an `HStack`'s vertical one, a `ZStack`'s frame alignment.
+    public var alignment: String
+
+    public init(props: JSONObject) {
+        spacing = props.double("spacing")
+        alignment = props.string("alignment") ?? "center"
+    }
+}
+
+public struct SpacerProps: Equatable, Sendable {
+    public var minLength: Double?
+    public init(props: JSONObject) { minLength = props.double("minLength") }
+}
+
+public struct ButtonProps: Equatable, Sendable {
+    /// `automatic`, `plain`, `bordered`, `borderedProminent`, `glass`.
+    public var style: String
+    /// `destructive`, `cancel` or nil.
+    public var role: String?
+    public var controlSize: String?
+    /// An `EditButton`: `active` or `inactive`, the mode it shows and flips.
+    public var editMode: String?
+
+    public init(props: JSONObject) {
+        style = props.string("style") ?? "automatic"
+        role = props.string("role")
+        controlSize = props.string("controlSize")
+        editMode = props.string("editMode")
+    }
+}
+
+/// An `image`: an SF Symbol, an asset catalog image, a remote URL or a bitmap recipe.
+public enum ImageProps: Equatable, Sendable {
+    case symbol(name: String, paletteRendering: Bool)
+    case asset(name: String, resizable: Bool)
+    case url(String, resizable: Bool, width: Double, height: Double)
+    case bitmap(recipe: JSONValue, resizable: Bool, width: Double, height: Double)
+    case unknown
+
+    public init(props: JSONObject) {
+        let resizable = props.bool("resizable") ?? false
+        if let name = props.string("systemName") {
+            self = .symbol(name: name, paletteRendering: props.string("renderingMode") == "palette")
+        } else if let name = props.string("name") {
+            self = .asset(name: name, resizable: resizable)
+        } else if let url = props.string("url") {
+            self = .url(url, resizable: resizable, width: props.double("width") ?? 0, height: props.double("height") ?? 0)
+        } else if let recipe = props["bitmap"] {
+            self = .bitmap(recipe: recipe, resizable: resizable, width: props.double("width") ?? 0, height: props.double("height") ?? 0)
+        } else {
+            self = .unknown
+        }
+    }
+}
+
+public struct ScrollViewProps: Equatable, Sendable {
+    /// `vertical`, `horizontal` or `both`.
+    public var axes: String
+    public var showsIndicators: Bool
+    public var refreshable: Bool
+    public init(props: JSONObject) {
+        axes = props.string("axes") ?? "vertical"
+        showsIndicators = props.bool("showsIndicators") ?? true
+        refreshable = props.bool("refreshable") ?? false
+    }
+}
+
+public struct ListProps: Equatable, Sendable {
+    /// `insetGrouped` (the default), `grouped`, `plain`, `sidebar`.
+    public var style: String
+    public var refreshable: Bool
+    public var editing: Bool?
+    public init(props: JSONObject) {
+        style = props.string("style") ?? "insetGrouped"
+        refreshable = props.bool("refreshable") ?? false
+        editing = props.bool("editing")
+    }
+}
+
+public struct SectionProps: Equatable, Sendable {
+    public var header: String?
+    public var footer: String?
+    public init(props: JSONObject) {
+        header = props.string("header")
+        footer = props.string("footer")
+    }
+}
+
+public struct TextFieldProps: Equatable, Sendable {
+    public var text: String
+    public var placeholder: String
+    /// `plain` or `roundedBorder`.
+    public var style: String
+    public var secure: Bool
+    public var focused: Bool?
+    public var submit: Bool
+    public var submitLabel: String?
+    public var vertical: Bool
+    public init(props: JSONObject) {
+        text = props.string("text") ?? ""
+        placeholder = props.string("placeholder") ?? ""
+        style = props.string("style") ?? "plain"
+        secure = props.bool("secure") ?? false
+        focused = props.bool("focused")
+        submit = props.bool("submit") ?? false
+        submitLabel = props.string("submitLabel")
+        vertical = props.string("axis") == "vertical"
+    }
+}
+
+public struct ToggleProps: Equatable, Sendable {
+    public var isOn: Bool
+    public init(props: JSONObject) { isOn = props.bool("isOn") ?? false }
+}
+
+public struct NavScreenProps: Equatable, Sendable {
+    public var title: String
+    /// `automatic`, `large` or `inline`.
+    public var displayMode: String
+    /// 0 for the stack's root screen.
+    public var depth: Int
+    public var toolbarRole: String?
+    public var backButtonHidden: Bool
+    public init(props: JSONObject) {
+        title = props.string("title") ?? ""
+        displayMode = props.string("displayMode") ?? "automatic"
+        depth = props.int("depth") ?? 0
+        toolbarRole = props.string("toolbarRole")
+        backButtonHidden = props.bool("backButtonHidden") ?? false
+    }
+}
+
+public struct NavLinkProps: Equatable, Sendable {
+    public var selected: Bool
+    public var plain: Bool
+    public init(props: JSONObject) {
+        selected = props.bool("selected") ?? false
+        plain = props.string("style") == "plain"
+    }
+}
+
+public struct ColorProps: Equatable, Sendable {
+    public var color: ColorSpec?
+    public init(props: JSONObject) { color = ColorSpec(json: props.value("color")) }
+}
+
+public struct StrokeSpec: Equatable, Sendable {
+    public var style: ShapeStyleSpec?
+    public var lineWidth: Double
+    public var inset: Bool
+    public var dash: [Double]
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        style = ShapeStyleSpec(json: fields.value("color"))
+        lineWidth = fields.double("lineWidth") ?? 1
+        inset = fields.bool("inset") ?? false
+        dash = (fields.array("dash") ?? []).compactMap(\.double)
+    }
+}
+
+public struct ShapeProps: Equatable, Sendable {
+    /// `rectangle`, `roundedRectangle`, `circle`, `capsule`, `ellipse`, `containerRelative`, `path`.
+    public var shape: String
+    public var cornerRadius: Double
+    /// Nil fills with the current foreground; `.some(nil)` is an explicit no fill.
+    public var fill: ShapeStyleSpec?
+    public var fillIsNull: Bool
+    public var stroke: StrokeSpec?
+    public var trimFrom: Double?
+    public var trimTo: Double?
+    public var path: String?
+    /// The size `path` was drawn for.
+    public var size: SizeSpec?
+    public init(props: JSONObject) {
+        shape = props.string("shape") ?? "rectangle"
+        cornerRadius = props.double("cornerRadius") ?? 0
+        fill = ShapeStyleSpec(json: props.value("fill"))
+        fillIsNull = props["fill"]?.isNull ?? true
+        stroke = StrokeSpec(json: props.value("stroke"))
+        trimFrom = props.object("trim")?.double("from")
+        trimTo = props.object("trim")?.double("to")
+        path = props.string("path")
+        size = SizeSpec(json: props.value("size"))
+    }
+}
+
+public struct SheetProps: Equatable, Sendable {
+    /// `medium`, `large`, `full`, `height:<points>`, `fraction:<f>`.
+    public var detents: [String]
+    public var interactiveDismissDisabled: Bool
+    public init(props: JSONObject) {
+        detents = (props.array("detents") ?? []).compactMap(\.string)
+        interactiveDismissDisabled = props.bool("interactiveDismissDisabled") ?? false
+    }
+    public var isFullScreen: Bool { detents == ["full"] }
+}
+
+public struct TabViewProps: Equatable, Sendable {
+    public var selected: Int
+    public init(props: JSONObject) { selected = props.int("selected") ?? 0 }
+}
+
+public struct TabProps: Equatable, Sendable {
+    public var title: String
+    public var systemImage: String?
+    public var image: String?
+    public var badge: String?
+    public var isSearch: Bool
+    public init(props: JSONObject) {
+        title = props.string("title") ?? ""
+        systemImage = props.string("systemImage")
+        image = props.string("image")
+        badge = props.string("badge")
+        isSearch = props.string("role") == "search"
+    }
+}
+
+public struct PickerProps: Equatable, Sendable {
+    /// `segmented`, `menu`, `inline`, `wheel`.
+    public var style: String
+    public var label: String
+    public var options: [String]
+    public var selected: Int
+    public init(props: JSONObject) {
+        style = props.string("style") ?? "menu"
+        label = props.string("label") ?? ""
+        options = (props.array("options") ?? []).compactMap(\.string)
+        selected = props.int("selected") ?? 0
+    }
+}
+
+public struct GeometryProps: Equatable, Sendable {
+    public var reportsFrame: Bool
+    public var reader: Int?
+    public init(props: JSONObject) {
+        reportsFrame = props.bool("reportsFrame") ?? false
+        reader = props.int("reader")
+    }
+}
+
+public struct ListRowProps: Equatable, Sendable {
+    public var selectable: Bool
+    public var selected: Bool
+    public var deletable: Bool
+    public var movable: Bool
+    public init(props: JSONObject) {
+        selectable = props.bool("selectable") ?? false
+        selected = props.bool("selected") ?? false
+        deletable = props.bool("deletable") ?? false
+        movable = props.bool("movable") ?? false
+    }
+}
+
+public struct ToolbarProps: Equatable, Sendable {
+    /// `trailing`, `leading`, `principal`, `bottom`, `secondary`, `largeTitle`.
+    public var placement: String
+    /// A `ToolbarSpacer`: `fixed` or `flexible`; the element has no items.
+    public var spacer: String?
+    /// `hidden` for `.sharedBackgroundVisibility(.hidden)`: no glass of the bar's around the items.
+    public var sharedBackground: String?
+    public init(props: JSONObject) {
+        placement = props.string("placement") ?? "trailing"
+        spacer = props.string("spacer")
+        sharedBackground = props.string("sharedBackground")
+    }
+}
+
+public struct SearchFieldProps: Equatable, Sendable {
+    public var text: String
+    public var placeholder: String
+    public init(props: JSONObject) {
+        text = props.string("text") ?? ""
+        placeholder = props.string("placeholder") ?? "Search"
+    }
+}
+
+public struct DecoratedProps: Equatable, Sendable {
+    /// `overlay` or `background`.
+    public var role: String
+    public var alignment: String
+    public init(props: JSONObject) {
+        role = props.string("role") ?? "overlay"
+        alignment = props.string("alignment") ?? "center"
+    }
+}
+
+public struct AlertProps: Equatable, Sendable {
+    public var title: String
+    public var message: String?
+    /// `alert` or `confirmationDialog`.
+    public var style: String
+    public init(props: JSONObject) {
+        title = props.string("title") ?? ""
+        message = props.string("message")
+        style = props.string("style") ?? "alert"
+    }
+}
+
+public struct StepperProps: Equatable, Sendable {
+    public var canIncrement: Bool
+    public var canDecrement: Bool
+    public init(props: JSONObject) {
+        canIncrement = props.bool("canIncrement") ?? true
+        canDecrement = props.bool("canDecrement") ?? true
+    }
+}
+
+public struct SliderProps: Equatable, Sendable {
+    public var value: Double
+    public var min: Double
+    public var max: Double
+    public var step: Double?
+    public init(props: JSONObject) {
+        value = props.double("value") ?? 0
+        min = props.double("min") ?? 0
+        max = props.double("max") ?? 1
+        step = props.double("step")
+    }
+}
+
+public struct TapGestureProps: Equatable, Sendable {
+    public var location: Bool
+    public init(props: JSONObject) { location = props.bool("location") ?? false }
+}
+
+/// The producer-only `native` kind (docs/native.md, "The native escape hatch").
+public struct NativeProps: Equatable, Sendable {
+    public var name: String
+    public var props: JSONValue
+    public init(props: JSONObject) {
+        name = props.string("name") ?? ""
+        self.props = props.value("props")
+    }
+}
+
+/// The root container's props (`update` of id 0): `.preferredColorScheme`.
+public struct RootProps: Equatable, Sendable {
+    /// `light`, `dark`, or nil for the viewer's setting.
+    public var colorScheme: String?
+    public init(props: JSONObject) { colorScheme = props.string("colorScheme") }
+}
+
+public struct GaugeProps: Equatable, Sendable {
+    /// Normalized to 0...1.
+    public var value: Double
+    /// `automatic`, `linearCapacity`, `accessoryLinear`, `accessoryCircular`, `accessoryCircularCapacity`, `progress`.
+    public var style: String
+    public var hasLabel: Bool
+    public var hasCurrentValueLabel: Bool
+    public init(props: JSONObject) {
+        value = min(1, max(0, props.double("value") ?? 0))
+        style = props.string("style") ?? "automatic"
+        hasLabel = props.bool("hasLabel") ?? false
+        hasCurrentValueLabel = props.bool("hasCurrentValueLabel") ?? false
+    }
+}
+
+public struct DatePickerProps: Equatable, Sendable {
+    /// Seconds since 1970.
+    public var seconds: Double
+    /// `date`, `hourAndMinute`, `dateAndTime`.
+    public var components: String
+    public var min: Double?
+    public var max: Double?
+    public var timeZone: String?
+    public var labelsHidden: Bool
+    public init(props: JSONObject) {
+        seconds = props.double("seconds") ?? 0
+        components = props.string("components") ?? "date"
+        min = props.double("min")
+        max = props.double("max")
+        timeZone = props.string("timeZone")
+        labelsHidden = props.bool("labelsHidden") ?? false
+    }
+}
+
+public struct GestureProps: Equatable, Sendable {
+    public var drag: Bool
+    public var longPress: Bool
+    public var minimumDistance: Double
+    public var minimumDuration: Double
+    public init(props: JSONObject) {
+        drag = props.bool("drag") ?? false
+        longPress = props.bool("longPress") ?? false
+        minimumDistance = props.double("minimumDistance") ?? 10
+        minimumDuration = props.double("minimumDuration") ?? 0.5
+    }
+}
+
+public struct ViewThatFitsProps: Equatable, Sendable {
+    /// `horizontal`, `vertical` or `both`.
+    public var axes: String
+    public init(props: JSONObject) { axes = props.string("axes") ?? "both" }
+}
+
+public struct LazySpacerProps: Equatable, Sendable {
+    public var axis: String
+    public var remaining: Int
+    public init(props: JSONObject) {
+        axis = props.string("axis") ?? "vertical"
+        remaining = props.int("remaining") ?? 0
+    }
+}
+
+/// `zstack` and `shape` props that ask for the element's laid-out size
+/// (`geometry` events, like a `GeometryReader`'s): anchor preferences, custom shapes.
+public struct SizeReportProps: Equatable, Sendable {
+    public var reportsSize: Bool
+    public var reportsFrame: Bool
+    public var reader: Int?
+    public init(props: JSONObject) {
+        reportsSize = props.bool("reportsSize") ?? false
+        reportsFrame = props.bool("reportsFrame") ?? false
+        reader = props.int("reader")
+    }
+}

package/swift/Sources/SwiftBrowserProtocol/RendererEvent.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+/// An event the renderer sends the app (docs/ops-protocol.md, "Events"):
+/// a `type`, usually the `id` of the element it concerns, and the fields of
+/// that type. Built with the constructors below and sent as JSON.
+public struct RendererEvent: Equatable, Sendable {
+    public var type: String
+    public var fields: JSONObject
+
+    public init(type: String, fields: JSONObject = [:]) {
+        self.type = type
+        self.fields = fields
+    }
+
+    /// The element the event names, when it names one.
+    public var id: Int? { fields.int("id") }
+
+    /// The event as a JSON object (`type` and the fields), sorted keys.
+    public var json: JSONValue {
+        var members = fields
+        members["type"] = .string(type)
+        return .object(members)
+    }
+
+    public var jsonString: String { json.json }
+
+    public init?(json: JSONValue) {
+        guard var members = json.object, let type = members["type"]?.string else { return nil }
+        members["type"] = nil
+        self.init(type: type, fields: members)
+    }
+
+    private static func with(_ type: String, id: Int, _ extra: JSONObject = [:]) -> RendererEvent {
+        var fields = extra
+        fields["id"] = .number(Double(id))
+        return RendererEvent(type: type, fields: fields)
+    }
+
+    /// A `button`, `navlink`, `tapgesture`, `listrow` was tapped; a `navscreen`'s back button; a `sheet` dismissed.
+    public static func tap(_ id: Int) -> RendererEvent { with("tap", id: id) }
+    /// A `tapgesture` with `location`.
+    public static func tap(_ id: Int, x: Double, y: Double) -> RendererEvent { with("tap", id: id, ["x": .number(x), "y": .number(y)]) }
+    /// A `textfield`, `searchfield` or `texteditor` received input.
+    public static func text(_ id: Int, _ value: String) -> RendererEvent { with("text", id: id, ["value": .string(value)]) }
+    /// A `toggle` was switched.
+    public static func toggle(_ id: Int, _ value: Bool) -> RendererEvent { with("toggle", id: id, ["value": .bool(value)]) }
+    /// A `tabview` item or `picker` option was chosen, by index.
+    public static func select(_ id: Int, _ index: Int) -> RendererEvent { with("select", id: id, ["value": .number(Double(index))]) }
+    /// A link run of a `text` was tapped.
+    public static func link(_ id: Int, _ url: String) -> RendererEvent { with("link", id: id, ["value": .string(url)]) }
+    /// A `geometry` element's laid-out size (and, with `reportsFrame`, its origin).
+    public static func geometry(_ id: Int, width: Double, height: Double, x: Double? = nil, y: Double? = nil) -> RendererEvent {
+        var fields: JSONObject = ["width": .number(width), "height": .number(height)]
+        if let x { fields["x"] = .number(x) }
+        if let y { fields["y"] = .number(y) }
+        return with("geometry", id: id, fields)
+    }
+    /// A `stepper` half was tapped (`value` is ±1).
+    public static func step(_ id: Int, _ delta: Int) -> RendererEvent { with("step", id: id, ["value": .number(Double(delta))]) }
+    /// A `slider` moved.
+    public static func slide(_ id: Int, _ value: Double) -> RendererEvent { with("slide", id: id, ["value": .number(value)]) }
+    /// A `datepicker` changed; `seconds` since 1970.
+    public static func date(_ id: Int, seconds: Double) -> RendererEvent { with("date", id: id, ["value": .number(seconds)]) }
+    /// A `textfield` with `focused` gained or lost focus.
+    public static func focus(_ id: Int, _ focused: Bool) -> RendererEvent { with("focus", id: id, ["value": .bool(focused)]) }
+    /// The Return key in a `textfield` with `submit`.
+    public static func submit(_ id: Int) -> RendererEvent { with("submit", id: id) }
+    /// A `listrow` was deleted by a swipe or in edit mode.
+    public static func delete(_ id: Int) -> RendererEvent { with("delete", id: id) }
+    /// A `listrow` was moved to index `to` among its siblings.
+    public static func move(_ id: Int, to: Int) -> RendererEvent { with("move", id: id, ["to": .number(Double(to))]) }
+    /// A `gesture` drag: `phase` is `began`, `changed`, `ended` or `cancelled`; points in the element's coordinates.
+    public static func drag(
+        _ id: Int, phase: String, translation: (width: Double, height: Double), location: (x: Double, y: Double),
+        startLocation: (x: Double, y: Double), velocity: (width: Double, height: Double)
+    ) -> RendererEvent {
+        with("drag", id: id, [
+            "phase": .string(phase),
+            "translation": .object(["width": .number(translation.width), "height": .number(translation.height)]),
+            "location": .object(["x": .number(location.x), "y": .number(location.y)]),
+            "startLocation": .object(["x": .number(startLocation.x), "y": .number(startLocation.y)]),
+            "velocity": .object(["width": .number(velocity.width), "height": .number(velocity.height)]),
+        ])
+    }
+    /// A `lazyspacer` came into view: the app mounts the next batch of rows.
+    public static func lazy(_ id: Int) -> RendererEvent { with("lazy", id: id) }
+    /// A `gesture` long press.
+    public static func longPress(_ id: Int) -> RendererEvent { with("longpress", id: id) }
+    /// A `list` or `scrollview` with `refreshable` was pulled.
+    public static func refresh(_ id: Int) -> RendererEvent { with("refresh", id: id) }
+    /// A `menu` opened or closed (lazy menus build their items on `open`).
+    public static func menu(_ id: Int, open: Bool) -> RendererEvent { with("menu", id: id, ["open": .bool(open)]) }
+    /// The host's answer to a `native` element's own event (docs/native.md, the escape hatch).
+    public static func native(_ id: Int, name: String, value: JSONValue) -> RendererEvent {
+        with("native", id: id, ["name": .string(name), "value": value])
+    }
+
+    /// The device appearance, text size or size class (sent once at launch and on change).
+    public static func environment(
+        colorScheme: String? = nil,
+        dynamicTypeSize: String? = nil,
+        horizontalSizeClass: String? = nil,
+        scenePhase: String? = nil
+    ) -> RendererEvent {
+        var fields: JSONObject = [:]
+        if let colorScheme { fields["colorScheme"] = .string(colorScheme) }
+        if let dynamicTypeSize { fields["dynamicTypeSize"] = .string(dynamicTypeSize) }
+        if let horizontalSizeClass { fields["horizontalSizeClass"] = .string(horizontalSizeClass) }
+        if let scenePhase { fields["scenePhase"] = .string(scenePhase) }
+        return RendererEvent(type: "environment", fields: fields)
+    }
+
+    /// Several events delivered at once; the app renders once for all of them.
+    public static func batch(_ events: [RendererEvent]) -> RendererEvent {
+        RendererEvent(type: "batch", fields: ["events": .array(events.map(\.json))])
+    }
+}