GoFlow

A Flutter-inspired GUI framework for Go with reactive state management and platform-adaptive design systems.

✨ Single Import Architecture

GoFlow uses a single import path for the best developer experience:

import gf "github.com/base-go/GoFlow"

func main() {
    count := gf.CreateSignal(0)

    app := gf.MaterialScaffold{
        AppBar: gf.MaterialAppBar{Title: "Counter"},
        Body: gf.Center{
            Child: gf.Text{
                Content: fmt.Sprintf("Count: %d", count.Get()),
            },
        },
    }

    gf.RunApp(app)
}

Migrating from the old multi-import style? See the Migration Guide

🚀 Quick Start

# Install the CLI
go install github.com/base-go/GoFlow/cmd/goflow@latest

# Create a new project (Flutter-style)
goflow create myapp

# Run it
cd myapp/macos
go run main.go

New to GoFlow? → Start with the Getting Started Guide

📚 Documentation

• Migration Guide - Switch to single import architecture
• Getting Started - Complete beginner tutorial
• Architecture - Framework architecture deep dive
• CLI Reference - Complete CLI documentation
• Project Structure - Project organization guide
• Rendering Architecture - How rendering works
• Flutter Comparison - For Flutter developers
• Workflow Guide - Complete technical flow
• All Documentation - Browse all docs

Project Structure

GoFlow follows Flutter's project structure philosophy:

myapp/
├── lib/                    # Shared application code (like Flutter's lib/)
│   └── main.go
├── macos/                  # macOS platform runner
├── linux/                  # Linux platform runner
├── windows/                # Windows platform runner
├── assets/                 # Images, fonts, icons
├── test/                   # Tests
├── goflow.yaml             # Project configuration (like pubspec.yaml)
├── go.mod                  # Go dependencies
└── README.md

Features

Core Framework

• Signal: Reactive value containers that notify listeners on change
• Computed: Automatically derived values with dependency tracking
• Effect: Side effects that run when dependencies change
• Batch: Group multiple updates to prevent unnecessary recomputation
• Untracked: Read signal values without creating subscriptions
• Collections: Reactive slices and maps with built-in helpers (Filter, Map, etc.)

GUI & Design Systems

• Adaptive Widgets: Automatically switch between Material and Cupertino based on platform
• Material Design: Google's design system (Android, Linux, Windows, Web)
• Cupertino: Apple's design language (iOS, macOS)
• Platform Detection: Automatic platform-specific styling
• Widget System: Declarative UI with reactive updates

Installation

go get github.com/base-go/GoFlow

Signals Quick Start

import gf "github.com/base-go/GoFlow"

// Create signals
counter := gf.CreateSignal(0)
doubled := gf.CreateComputed(func() int {
    return counter.Get() * 2
})

// React to changes
dispose := gf.CreateEffect(func() {
    fmt.Printf("Counter: %d, Doubled: %d\n", counter.Get(), doubled.Get())
})
defer dispose()

// Update (triggers effect)
counter.Set(5) // Prints: Counter: 5, Doubled: 10

Collections

GoFlow includes reactive collections for common data structures:

SignalSlice

// Create a reactive slice
todos := signals.NewSlice([]string{"Learn Go", "Build app"})

// Reactive operations
todos.Append("Deploy to production")
todos.Prepend("Plan project")
todos.RemoveAt(1)

// Reactive computed operations
activeTodos := todos.Filter(func(todo string) bool {
    return !strings.HasPrefix(todo, "Done:")
})

// Get length reactively
count := todos.Len()
fmt.Printf("Total todos: %d\n", count.Get())

SignalMap

// Create a reactive map
users := signals.NewMap(map[string]int{
    "alice": 25,
    "bob": 30,
})

// Reactive operations
users.SetKey("charlie", 35)
users.DeleteKey("bob")

// Reactive queries
hasAlice := users.Has("alice")
aliceAge := users.GetKey("alice")
userCount := users.Size()

Advanced Usage

Batch Updates

Prevent unnecessary re-computations by batching multiple updates:

signals.Batch(func() {
    firstName.Set("John")
    lastName.Set("Doe")
    age.Set(30)
})
// Effect runs only once after all updates

Untracked Reads

Read signal values without creating dependencies:

dispose := signals.NewEffect(func() {
    current := counter.Get() // Tracked
    previous := signals.Untracked(func() int {
        return prevCounter.Get() // Not tracked
    })
    fmt.Printf("Changed from %d to %d\n", previous, current)
})

Design Systems

GoFlow provides three approaches to building cross-platform UIs:

Adaptive Widgets (Recommended)

Write once, automatically adapts to platform:

import "github.com/base-go/GoFlow/pkg/ui/adaptive"

// Button automatically becomes Material or Cupertino
button := adaptive.NewButton("Click Me", func() {
    fmt.Println("Clicked!")
})

// Card adapts to platform style
card := adaptive.NewCard(content)

// AppBar becomes Material AppBar or Cupertino NavigationBar
appBar := adaptive.NewAppBar(title)

Platform-Specific Widgets

Use Material Design or Cupertino explicitly:

// Material Design (Android, Web, Desktop)
import "github.com/base-go/GoFlow/pkg/ui/material"
btn := material.NewButton(child, onPressed)

// Cupertino (iOS, macOS)
import "github.com/base-go/GoFlow/pkg/ui/cupertino"
btn := cupertino.NewButton(child, onPressed)

See DESIGN_SYSTEMS.md for complete documentation.

Available Widgets

GoFlow includes a comprehensive set of widgets inspired by Flutter:

Layout Widgets

• Column/Row: Vertical/horizontal layout
• Stack: Layered widgets
• Positioned: Position children within Stack
• Align: Align child within parent
• Container: Padding, margin, sizing, colors
• Center: Center child widget
• Padding: Add padding around child
• SizedBox: Fixed size container
• Expanded/Flexible: Flex children in Row/Column
• Spacer: Empty space in flex layouts

Form Widgets

• TextField (Material/Cupertino): Text input
• Checkbox: Material checkbox
• Radio: Material radio button
• Switch (Material/Cupertino): Toggle switch
• Slider (Material/Cupertino): Value slider

Button Widgets

• Button (Material/Cupertino): Primary buttons
• TextButton: Text-only button (Material)
• OutlinedButton: Outlined button (Material)
• IconButton: Button with icon
• FloatingActionButton: Material FAB

Display Widgets

• Text: Display text
• Icon: Display icons
• Image: Display images

Scrolling Widgets

• ListView: Scrollable list
• ListView.builder: Lazy-loaded list
• GridView: Scrollable grid
• SingleChildScrollView: Scrollable single child

Interaction Widgets

• GestureDetector: Detect gestures
• InkWell: Material ink splash effect
• Draggable: Make widget draggable
• DragTarget: Accept draggable widgets

App Structure

• Scaffold (Material): Basic app structure
• AppBar (Material): Top app bar
• Drawer: Side navigation drawer
• BottomNavigationBar: Bottom navigation
• CupertinoPageScaffold: iOS app structure
• CupertinoNavigationBar: iOS navigation bar
• CupertinoTabScaffold: iOS tabbed interface

Material-Specific

• Card: Material card
• ListTile: List item with leading/trailing
• Dialog: Material dialog
• AlertDialog: Alert dialog with actions
• DrawerHeader: Drawer header

Cupertino-Specific

• CupertinoTextField: iOS text field
• CupertinoSwitch: iOS switch
• CupertinoSlider: iOS slider

📚 See docs/widgets/ for detailed widget documentation with examples

📖 Examples

See the examples directory for complete examples:

Signals Examples

• Playground - Comprehensive framework feature test
• Basic - Simple signal usage
• Counter App - Interactive counter with multiple computed values
• Shopping Cart - Shopping cart with reactive total
• Form Validation - Real-time form validation
• Todo List - Todo list using SignalSlice

Design System Examples

• Adaptive Demo - Platform-adaptive widgets
• Material Demo - Material Design widgets
• Cupertino Demo - iOS/macOS widgets
• Widgets Showcase - Comprehensive widget demonstration

⚡ Performance

GoFlow is designed for performance with:

• Zero allocations for basic signal operations
• Lazy evaluation for computed values
• Efficient dependency tracking using graph algorithms
• Thread-safe operations with minimal locking overhead

Run benchmarks:

go test ./signals -bench=. -benchmem

🎨 Framework Status (v0.2.0)

✅ What Works

• Widget system (Text, Container, Column, Center)
• Reactive signals (Signal, Computed, Effect)
• Signal collections (SignalSlice, SignalMap)
• Layout system (constraints, sizing)
• Three-tree architecture (Widget → Element → RenderObject)
• CLI tool for project creation
• Flutter-inspired project structure
• ✨ macOS Rendering Backend - Core Graphics with native windows
• ✨ Text Rendering - Core Text integration
• ✨ Basic Shapes - Rectangles, circles, lines
• ✨ Event Loop - Native event handling

⏳ In Progress

• Mouse and keyboard event handling
• Image loading and rendering
• More built-in widgets
• Design system implementations (Material, Cupertino)

🔮 Planned

• Windows rendering backend (Direct2D)
• Linux rendering backend (Cairo)
• Hot reload
• Animation system
• Advanced layout widgets (Row, Stack, Grid)
• Input widgets (TextField, Button)
• Platform features (menus, notifications)
• Complete Material Design implementation
• Complete Cupertino implementation

See RENDERING.md, PLATFORM_INTEGRATION.md, and PROGRESS.md for details.

🤝 Contributing

GoFlow is in active development! We welcome contributions:

• 🐛 Report bugs
• 💡 Suggest features
• 📖 Improve documentation
• 🔧 Submit pull requests

See our GitHub repository for more information.

📚 Learn More

• Architecture Guide - Deep dive into the framework
• Getting Started - Step-by-step tutorial
• Workflow Guide - Complete technical flow
• Widget Reference - Complete widget catalog
• Examples - Sample applications
• API Documentation - Go package docs

License

MIT