TUIkit/TUIKit.docc/Tutorials/BuildYourFirstApp.md

# Building Your First App

Create a simple counter application to learn TUIKit basics.

@Intro(title: "Create Your First TUIKit App") {
    Learn the fundamentals of building a terminal user interface with TUIKit
    by creating a simple counter application.

    You'll learn how to set up an `@main` app, use `@State` for local state,
    add interactive buttons, and use basic layout with `VStack` and `HStack`.
}

## Overview

In this tutorial, you'll build a working counter app with increment/decrement buttons.
This will teach you:

- Creating an app with the `@main` attribute
- Using `VStack` and `HStack` for layout
- Handling button taps with `@State`
- Running and testing your app

@Section(title: "Create the App Entry Point") {
    @ContentAndMedia {
        Every TUIKit app needs an entry point decorated with `@main`.
        This tells Swift to use your app as the entry point for the program.
    }

    @Steps {
        @Step {
            Create a new file called `main.swift` in your project:

            ```swift
            import TUIKit

            @main
            struct CounterApp: App {
                var body: some Scene {
                    WindowGroup {
                        Text("Hello, TUIKit!")
                    }
                }
            }
            ```

            The `@main` attribute marks this as the app entry point.
            `WindowGroup` represents the main window of your terminal app.
        }

        @Step {
            Run your app with:

            ```bash
            swift run
            ```

            You should see "Hello, TUIKit!" displayed in the terminal.
        }
    }
}

@Section(title: "Add Layout and Text") {
    @ContentAndMedia {
        Now let's organize content with `VStack` (vertical layout).
        We'll add a title and multiple text lines.
    }

    @Steps {
        @Step {
            Modify the `body` to use `VStack`:

            ```swift
            @main
            struct CounterApp: App {
                var body: some Scene {
                    WindowGroup {
                        VStack(spacing: 1) {
                            Text("Counter App")
                                .bold()

                            Text("Simple counter to learn TUIKit")
                                .foregroundColor(.theme.foregroundSecondary)

                            Spacer()

                            Text("Current count: 0")

                            Spacer()
                        }
                        .padding()
                    }
                }
            }
            ```

            - `VStack(spacing: 1)` arranges content vertically with 1-unit spacing
            - `.bold()` makes the title bold
            - `.foregroundColor()` colors text
            - `Spacer()` creates flexible vertical space
            - `.padding()` adds space around all edges
        }

        @Step {
            Run the app again:

            ```bash
            swift run
            ```

            Now you should see a nicely formatted display with title,
            description, and spacing.
        }
    }
}

@Section(title: "Add Interactive State") {
    @ContentAndMedia {
        Use `@State` to track the counter value and re-render when it changes.
        This makes your app interactive!
    }

    @Steps {
        @Step {
            Add a `@State` property for the counter:

            ```swift
            @main
            struct CounterApp: App {
                @State private var count: Int = 0

                var body: some Scene {
                    WindowGroup {
                        VStack(spacing: 1) {
                            Text("Counter App")
                                .bold()

                            Text("Simple counter to learn TUIKit")
                                .foregroundColor(.theme.foregroundSecondary)

                            Spacer()

                            Text("Current count: \(count)")

                            Spacer()
                        }
                        .padding()
                    }
                }
            }
            ```

            The `@State` property wrapper stores local state. When `count` changes,
            the view automatically re-renders.
        }
    }
}

@Section(title: "Add Buttons") {
    @ContentAndMedia {
        Now add buttons to increment and decrement the counter.
        Use `HStack` to arrange them horizontally.
    }

    @Steps {
        @Step {
            Add buttons using `HStack`:

            ```swift
            @main
            struct CounterApp: App {
                @State private var count: Int = 0

                var body: some Scene {
                    WindowGroup {
                        VStack(spacing: 1) {
                            Text("Counter App")
                                .bold()

                            Text("Simple counter to learn TUIKit")
                                .foregroundColor(.theme.foregroundSecondary)

                            Spacer()

                            Text("Current count: \(count)")

                            HStack(spacing: 2) {
                                Button("Decrement") { count -= 1 }
                                Button("Increment") { count += 1 }
                            }

                            Spacer()

                            Text("Press 'q' to quit")
                                .foregroundColor(.theme.foregroundTertiary)
                        }
                        .padding()
                    }
                }
            }
            ```

            - `HStack(spacing: 2)` arranges buttons horizontally
            - `Button(label) { action }` creates a clickable button
            - The closure after the label runs when the button is pressed
        }

        @Step {
            Run your app:

            ```bash
            swift run
            ```

            Now use Tab to navigate to the buttons and press Enter to increment/decrement.
            The counter value updates in real-time!
        }
    }
}

@Section(title: "Test and Iterate") {
    @ContentAndMedia {
        Test your counter app and try making improvements.
    }

    @Steps {
        @Step {
            Test the following interactions:

            - Press `Tab` to move focus to the next button
            - Press `Shift+Tab` to move focus backward
            - Press `Enter` when a button is focused to activate it
            - Watch the counter update
            - Press `q` to quit the app
            - Press `t` to cycle through themes
            - Press `a` to cycle through appearance styles
        }

        @Step {
            Try these enhancements:

            Add a reset button:

            ```swift
            HStack(spacing: 2) {
                Button("Decrement") { count = max(0, count - 1) }
                Button("Reset") { count = 0 }
                Button("Increment") { count += 1 }
            }
            ```

            Or add a border around the counter:

            ```swift
            Text("Current count: \(count)")
                .bold()
                .padding(1)
                .border(.rounded)
            ```
        }
    }
}

## Next Steps

Congratulations! You've built your first TUIKit app.

- Learn more about <doc:StateManagement> for complex state scenarios
- Explore <doc:Theming> to customize colors
- Try building an interactive <doc:BuildInteractiveMenu>
- Check out <doc:Modifiers> for more styling options