Build the pieces of a tiny UI framework

Set up the project in Xcode

Over today and tomorrow you build TinyUI, a miniature SwiftUI that draws with text in the console. Today's project holds its widgets. It is a new project, set up from scratch in the same way as yesterday's:

1. Open Xcode and choose File ▸ New ▸ Project… (⇧⌘N). If you are looking at the Welcome to Xcode window instead, its New Project menu offers the same choices.

2. Xcode 27 shows a short list of project kinds. Click Choose Template.

3. A sheet titled Choose a template for your new project appears. In the row of platforms at the top, click macOS. Under Application, select Command Line Tool. Click Next.

4. Fill in the options. Product Name: Widgets. Team: leave it as it is — a command-line program does not need one. Organization Identifier: the one you normally use, such as com.yourname. Language: Swift. Click Next.

5. Choose the folder to keep the project in — your Development folder, for example. Tick Create Git repository on my Mac or not, as you prefer. Click Create.

6. The project window opens. In the Project navigator on the left, open the Widgets folder and click main.swift. Below a comment that gives the file's name and today's date, Xcode has written:

   main.swift, as Xcode made it

   import Foundation
   
   print("Hello, World!")

7. Check that the run destination in the toolbar says My Mac, then choose Product ▸ Run (⌘R). The debug area opens at the bottom of the window, and its console shows:

   Console

   Hello, World!
   Program ended with exit code: 0

   The last line comes from Xcode, not from the program: it says the program has finished, and 0 means it finished without an error. If you cannot see the console, choose View ▸ Debug Area ▸ Activate Console (⇧⌘C).

8. Now add a second file. With main.swift still selected, choose File ▸ New ▸ File from Template… (⌘N). Under Source, select Swift File. Click Next.

9. Name it Widgets, leave the other settings as they are, and click Create. The file appears beside main.swift and opens with a comment and one line of code: import Foundation. Leave that line where it is.

As yesterday: types go in Widgets.swift, and the code that tries them out goes in main.swift, below import Foundation.

A protocol for things that can draw themselves

In TinyUI, a widget is anything that can turn itself into lines of text. That is the whole protocol. Text is the simplest widget: it renders as one line.

protocol Widget {
    func render() -> [String]          // a widget draws itself as lines of text
}

struct Text: Widget {
    let string: String
    init(_ string: String) { self.string = string }

    func render() -> [String] { [string] }
}

func show(_ widget: some Widget) {
    print(widget.render().joined(separator: "\n"))
}

show(Text("Seattle"))

Run it (⌘R). The console shows

Seattle
Program ended with exit code: 0

Containers: Column and Bordered

A container is a widget that holds other widgets. Column holds two and puts one above the other. Bordered holds one and draws a box around it.

struct Column<Top: Widget, Bottom: Widget>: Widget {
    let top: Top
    let bottom: Bottom
    init(_ top: Top, _ bottom: Bottom) {
        self.top = top
        self.bottom = bottom
    }

    func render() -> [String] { top.render() + bottom.render() }
}

struct Bordered<Content: Widget>: Widget {
    let content: Content
    init(_ content: Content) { self.content = content }

    func render() -> [String] {
        let lines = content.render()
        let width = lines.map(\.count).max() ?? 0
        let edge = "+" + String(repeating: "-", count: width + 2) + "+"
        let rows = lines.map { "| " + $0.padding(toLength: width, withPad: " ", startingAt: 0) + " |" }
        return [edge] + rows + [edge]
    }
}

show(Bordered(Column(Text("Seattle"), Text("Aug 22 - Sep 3"))))

Run it (⌘R). The console shows

+----------------+
| Seattle        |
| Aug 22 - Sep 3 |
+----------------+
Program ended with exit code: 0

Notice the angle brackets. Bordered<Content: Widget> is generic: it works with any content that is a Widget, and the type of that content becomes part of Bordered's own type. That detail is about to matter.

A function that returns a widget

Move the card into a function. A function has to declare what type it returns, so write it out:

func tripCard() -> Bordered<Column<Text, Text>> {
    Bordered(Column(Text("Seattle"), Text("Aug 22 - Sep 3")))
}

let card = tripCard()
show(card)
print(type(of: card))

Run it (⌘R). The console shows

+----------------+
| Seattle        |
| Aug 22 - Sep 3 |
+----------------+
Bordered<Column<Text, Text>>
Program ended with exit code: 0

The last line of output is the type: Bordered<Column<Text, Text>>. The type records the whole structure of the card. That is useful to the compiler, and unpleasant for you: every time you change what is inside the card, you must rewrite the return type to match. With ten nested widgets it would be unreadable.

some Widget: let the compiler keep track of the type

Change one thing: the return type.

func tripCard() -> some Widget {
    Bordered(Column(Text("Seattle"), Text("Aug 22 - Sep 3")))
}

let card = tripCard()
show(card)
print(type(of: card))

Run it (⌘R). The console shows

+----------------+
| Seattle        |
| Aug 22 - Sep 3 |
+----------------+
Bordered<Column<Text, Text>>
Program ended with exit code: 0

The output is identical, including the type on the last line. some Widget did not change what the function returns. It still returns exactly a Bordered<Column<Text, Text>>, and the compiler still knows that. You simply no longer have to write it.

This is called an opaque type. The function promises: "I return one specific type that is a Widget. I know which. You do not need to." Code that calls the function cannot depend on the hidden type:

let card: Bordered<Column<Text, Text>> = tripCard()
show(card)

It does not compile. Xcode reports

cannot convert value of type 'some Widget' to specified type 'Bordered<Column<Text, Text>>'

Undo that change (⌘Z), so that main.swift is back to the three lines that ran. The point is made: the type is hidden from callers, not erased.

The rule you will meet in SwiftUI: one type only

Now write a function that returns a different widget depending on a condition:

func badge(isNew: Bool) -> some Widget {
    if isNew {
        return Text("NEW")
    } else {
        return Bordered(Text("seen"))
    }
}

It does not compile. Xcode reports

function declares an opaque return type 'some Widget', but the return statements in its body do not have matching underlying types

Read that message carefully, because you will see it in SwiftUI with the word View in place of Widget. some Widget means one type. This function tries to return a Text on one path and a Bordered<Text> on the other. Those are two types, and the promise is broken.

There are three ways out. Each one is a real technique that SwiftUI uses, and the next three steps try them in turn.

Way out 1: any Widget

Change some to any:

func badge(isNew: Bool) -> any Widget {
    if isNew {
        return Text("NEW")
    } else {
        return Bordered(Text("seen"))
    }
}

show(badge(isNew: true))
show(badge(isNew: false))
print(type(of: badge(isNew: true)), type(of: badge(isNew: false)))

Run it (⌘R). The console shows

NEW
+------+
| seen |
+------+
Text Bordered<Text>
Program ended with exit code: 0

It compiles, and the last line shows why: the two calls really did return values of two different types. any Widget is a box that can hold a value of any type that conforms to Widget. Which type is inside is only known while the program runs.

That flexibility has a price. Try to put the result in a border:

show(Bordered(badge(isNew: true)))

It does not compile. Xcode reports

type 'any Widget' cannot conform to 'Widget'

Bordered is generic: it needs to know the exact type of its content when the code is compiled. A box whose contents are only known later cannot tell it. (Calling show worked because Swift can open the box for the length of a single function call. It cannot do that when the type would have to become part of another type.)

Way out 2: erase the type

You can write a concrete type whose job is to hide another widget inside it. It holds on to the widget's render function and forgets everything else:

struct AnyWidget: Widget {
    private let renderer: () -> [String]
    init(_ widget: some Widget) { renderer = widget.render }

    func render() -> [String] { renderer() }
}

func badge(isNew: Bool) -> AnyWidget {
    if isNew {
        return AnyWidget(Text("NEW"))
    } else {
        return AnyWidget(Bordered(Text("seen")))
    }
}

show(Bordered(badge(isNew: true)))
print(type(of: badge(isNew: true)), type(of: badge(isNew: false)))

Run it (⌘R). The console shows

+-----+
| NEW |
+-----+
AnyWidget AnyWidget
Program ended with exit code: 0

Now Bordered is happy, because AnyWidget is one concrete type. But look at the last line: both badges report the type AnyWidget. The information about what is inside has been thrown away.

Way out 3: one type that can hold either

The third way keeps all the type information. Define a single type with two cases, one for each possibility:

enum Either<First: Widget, Second: Widget>: Widget {
    case first(First)
    case second(Second)

    func render() -> [String] {
        switch self {
        case .first(let widget):  widget.render()
        case .second(let widget): widget.render()
        }
    }
}

func badge(isNew: Bool) -> some Widget {
    if isNew {
        return Either<Text, Bordered<Text>>.first(Text("NEW"))
    } else {
        return Either<Text, Bordered<Text>>.second(Bordered(Text("seen")))
    }
}

show(badge(isNew: true))
show(Bordered(badge(isNew: false)))
print(type(of: badge(isNew: true)))

Run it (⌘R). The console shows

NEW
+----------+
| +------+ |
| | seen | |
| +------+ |
+----------+
Either<Text, Bordered<Text>>
Program ended with exit code: 0

The function returns some Widget again, and the promise holds, because both branches return the same type: Either<Text, Bordered<Text>>. The type spells out both possibilities, so nothing is lost.

SwiftUI does precisely this. Its version is called _ConditionalContent, and it is what an if/else inside a view's body turns into. You never write it yourself — tomorrow you will build the feature that writes it for you.

some in a parameter

Look back at the first function you wrote today: func show(_ widget: some Widget). That is some used in a parameter. There it is shorthand for a generic function, func show<W: Widget>(_ widget: W). The two mean the same thing.

So, in one sentence each. In a return type, some means "one specific type, chosen by the function, which the caller is not told". In a parameter, it means "any one type the caller chooses". And any means "a box that can hold a value of any conforming type, decided while the program runs".

Keep today's project. Tomorrow's builds on Widgets.swift.