# zcatgui

**Immediate Mode GUI Library for Zig** - Software-rendered, cross-platform, SSH-compatible.

[![Zig](https://img.shields.io/badge/Zig-0.15.2-orange)](https://ziglang.org/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Features

- **Immediate Mode** - Explicit state, no callbacks, no threading issues
- **Software Rendering** - Works everywhere, including over SSH (X11 forwarding)
- **Macro System** - Record and replay user actions (unique feature)
- **35 Widgets** - From basic (Button, Label) to advanced (Table, Tree, Charts)
- **5 Themes** - Dark, Light, High Contrast, Nord, Dracula
- **Accessibility** - ARIA-like roles and states for screen readers
- **Zero Runtime Dependencies** - Only SDL2 for windowing

## Quick Start

```zig
const zcatgui = @import("zcatgui");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    var ctx = try zcatgui.Context.init(allocator);
    defer ctx.deinit();

    while (ctx.running) {
        ctx.beginFrame();

        if (zcatgui.button(&ctx, "Click me!")) {
            // Handle click
        }

        ctx.endFrame();
    }
}
```

## Widgets (35 total)

### Basic
- **Label** - Static text with alignment options
- **Button** - Primary, normal, danger variants
- **Checkbox** - Boolean toggle
- **RadioButton** - Mutually exclusive selection

### Input
- **TextInput** - Single-line text entry with cursor
- **TextArea** - Multi-line text editor
- **NumberInput** - Numeric input with validation
- **Slider** - Horizontal/vertical value slider
- **AutoComplete** - ComboBox with fuzzy matching

### Selection
- **Select** - Dropdown selection
- **List** - Scrollable selectable list
- **Tree** - Hierarchical tree view

### Data
- **Table** - Editable with sorting, validation, dirty tracking
- **LineChart** - Line graphs with multiple series
- **BarChart** - Bar graphs with grouping
- **PieChart** - Pie/donut charts with labels
- **Sparkline** - Compact inline charts

### Layout
- **Panel** - Container with title, collapsible
- **HSplit/VSplit** - Draggable split panels
- **Tabs** - Tab container with keyboard navigation
- **ScrollArea** - Scrollable content region
- **Modal** - Dialog boxes (alert, confirm, input)

### Feedback
- **Progress** - Bar, circle, spinner with animations
- **Tooltip** - Hover tooltips with smart positioning
- **Toast** - Non-blocking notifications
- **Badge** - Status labels with variants

### Navigation
- **Menu** - Dropdown menus with submenus
- **ContextMenu** - Right-click menus

### Special
- **Image** - Image display with scaling
- **Icon** - Icon rendering
- **ColorPicker** - Color selection
- **Calendar** - Date selection
- **RichText** - Styled text rendering

## Unique Features

### Macro System

Record user actions as keyboard events and replay them:

```zig
var recorder = zcatgui.MacroRecorder.init(allocator);

// Start recording
recorder.start();

// ... user interacts with UI ...

// Stop and save
const events = recorder.stop();
try recorder.save("my_macro.macro");

// Later, replay
var player = zcatgui.MacroPlayer.init();
player.play(events, ctx.injectEvent, 50); // 50ms delay between events
```

### Lego Panels Architecture

Build complex UIs from reusable autonomous panels:

```zig
const panels = zcatgui.panels;

var search_panel = panels.SearchFilterPanel.init(allocator, config);
var data_panel = panels.DataTablePanel.init(allocator, table_config);

// Panels communicate via DataManager
var manager = panels.DataManager.init(allocator);
manager.register("search", &search_panel);
manager.register("data", &data_panel);
```

### Table with Dirty Tracking

Track changes for database sync:

```zig
var table_state = zcatgui.widgets.TableState.init();

// After user edits
if (table_state.isDirty()) {
    const changes = table_state.getDirtyRows();
    for (changes) |row_idx| {
        // Sync to database
    }
    table_state.clearDirty();
}
```

## Themes

```zig
const theme = zcatgui.Style.ThemeManager.init();

// Switch themes at runtime
theme.setTheme(.dark);
theme.setTheme(.light);
theme.setTheme(.high_contrast);
theme.setTheme(.nord);
theme.setTheme(.dracula);
```

## Performance

- **FrameArena** - O(1) per-frame allocator with automatic reset
- **ObjectPool** - Reuse frequently allocated objects
- **Virtual Scrolling** - Handle millions of items efficiently
- **Dirty Rectangles** - Partial redraws for efficiency

## Building

```bash
# Build library
zig build

# Run tests
zig build test

# Build examples
zig build hello
zig build widgets-demo
zig build table-demo
```

## Requirements

- Zig 0.15.2
- SDL2 (for windowing)

## Project Structure

```
zcatgui/
├── src/
│   ├── zcatgui.zig      # Main entry point
│   ├── core/            # Context, Layout, Style, Input
│   ├── widgets/         # All 35 widgets
│   ├── render/          # Software renderer, fonts, effects
│   ├── backend/         # SDL2 backend
│   ├── macro/           # Macro recording/playback
│   ├── panels/          # Lego Panels architecture
│   └── utils/           # Performance utilities
├── examples/            # Demo applications
└── docs/               # Documentation
```

## Comparison

| Feature | zcatgui | DVUI | Dear ImGui |
|---------|:-------:|:----:|:----------:|
| Language | Zig | Zig | C++ |
| Rendering | Software | Software/GPU | GPU |
| SSH Compatible | Yes | Partial | No |
| Macro System | Yes | No | No |
| Table Dirty Tracking | Yes | No | No |
| Widgets | 35 | 33 | 30+ |

## Related Projects

- **zcatui** - TUI (Terminal UI) library for Zig (sister project)

## License

MIT License - See [LICENSE](LICENSE) for details.

## Contributing

Issues and pull requests welcome at the project repository.