{"id":45908839,"url":"https://github.com/yusa-imit/sailor","last_synced_at":"2026-06-14T02:10:05.240Z","repository":{"id":341051429,"uuid":"1168666090","full_name":"yusa-imit/sailor","owner":"yusa-imit","description":"Zig TUI framework \u0026 CLI toolkit","archived":false,"fork":false,"pushed_at":"2026-04-27T09:24:19.000Z","size":2495,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T11:04:26.185Z","etag":null,"topics":["cli","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yusa-imit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDIT_DOC_COMMENTS.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T16:52:41.000Z","updated_at":"2026-04-27T09:24:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"5383ba21-2234-420a-b8b2-514b88afc89a","html_url":"https://github.com/yusa-imit/sailor","commit_stats":null,"previous_names":["yusa-imit/sailor"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/yusa-imit/sailor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusa-imit%2Fsailor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusa-imit%2Fsailor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusa-imit%2Fsailor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusa-imit%2Fsailor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yusa-imit","download_url":"https://codeload.github.com/yusa-imit/sailor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusa-imit%2Fsailor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32542201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","zig"],"created_at":"2026-02-28T05:00:05.636Z","updated_at":"2026-05-02T17:01:06.154Z","avatar_url":"https://github.com/yusa-imit.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sailor 🚢\n\n\u003e A modern Zig TUI framework \u0026 CLI toolkit with zero dependencies.\n\nsailor is a batteries-included library for building terminal applications in Zig. From simple CLI tools with colored output to full-featured TUI applications with complex layouts and widgets — sailor has you covered.\n\n**Key Features:**\n- 🎨 **Rich CLI** - Styled output, progress bars, tables, REPL\n- 🖥️ **Full TUI** - Layout system, 40+ widgets, event handling\n- 🌐 **Network \u0026 Async** - HTTP, WebSocket, background tasks, log streaming\n- 🔧 **Modular** - Use only what you need, each module is independent\n- 🌍 **Cross-platform** - Linux, macOS, Windows (x86_64 \u0026 ARM64)\n- 🚀 **Zero dependencies** - Only the Zig standard library\n- 📦 **Library-first** - No global state, bring your own allocator\n\n## Quick Start\n\n```zig\nconst std = @import(\"std\");\nconst sailor = @import(\"sailor\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n\n    var terminal = try sailor.tui.Terminal.init(gpa.allocator());\n    defer terminal.deinit();\n\n    try terminal.run(render);\n}\n\nfn render(frame: *sailor.tui.Frame) !void {\n    const block = sailor.tui.widgets.Block.init()\n        .setTitle(sailor.tui.Line.fromString(\"Hello, sailor!\"))\n        .setBorders(sailor.tui.Borders.all);\n\n    const para = sailor.tui.widgets.Paragraph.init(\n        sailor.tui.Line.fromString(\"Press Ctrl+C to exit\")\n    ).setBlock(block);\n\n    frame.renderWidget(para, frame.size());\n}\n```\n\n## Modules\n\n| Module | Description | Version |\n|--------|-------------|---------|\n| **term** | Terminal backend (raw mode, key reading, TTY detection, size) | ✅ v0.1.0 |\n| **color** | Styled output (ANSI codes, 256/truecolor, NO_COLOR support) | ✅ v0.1.0 |\n| **arg** | Argument parser (flags, subcommands, auto-help) | ✅ v0.1.0 |\n| **repl** | Interactive REPL (line editing, history, completion) | ✅ v0.2.0 |\n| **progress** | Progress indicators (bar, spinner, multi-progress) | ✅ v0.2.0 |\n| **fmt** | Result formatting (table, JSON, CSV, plain text) | ✅ v0.2.0 |\n| **tui** | Full-screen TUI framework (layout, widgets, events) | ✅ v0.3.0 |\n\n## Widgets\n\n**Core Widgets** (v0.4.0):\nBlock, Paragraph, List, Table, Input, Tabs, StatusBar, Gauge\n\n**Advanced Widgets** (v0.5.0):\nTree, TextArea, Sparkline, BarChart, LineChart, Canvas, Dialog, Popup, Notification\n\n**Data Visualization** (v1.6.0):\nHeatmap, PieChart, ScatterPlot, Histogram, TimeSeriesChart\n\n**Network \u0026 Async** (v1.8.0):\nHttpClient, WebSocket, TaskRunner, LogViewer\n\nSee the [Widget Gallery](docs/GUIDE.md#widget-gallery) for examples.\n\n## Documentation\n\n- **[Getting Started Guide](docs/GUIDE.md)** - Tutorials and examples\n- **[API Reference](docs/API.md)** - Complete API documentation\n- **[PRD](docs/PRD.md)** - Design rationale and architecture\n\n## Installation\n\n**Requirements:** Zig 0.15.x or later\n\nAdd to your `build.zig.zon`:\n\n```zig\n.{\n    .name = \"myapp\",\n    .version = \"0.1.0\",\n    .paths = .{\"\"},\n    .dependencies = .{\n        .sailor = .{\n            .path = \"../sailor\",  // Local development\n            // .url = \"https://...\",  // Or git URL when published\n        },\n    },\n}\n```\n\nUpdate `build.zig`:\n\n```zig\nconst sailor = b.dependency(\"sailor\", .{\n    .target = target,\n    .optimize = optimize,\n});\nexe.root_module.addImport(\"sailor\", sailor.module(\"sailor\"));\n```\n\nSee the [installation guide](docs/GUIDE.md#installation) for details.\n\n## Examples\n\n### CLI with Styled Output\n\n```zig\nconst sailor = @import(\"sailor\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n\n    try sailor.color.ok(stdout, \"✓ Build successful\\n\");\n    try sailor.color.err(stdout, \"✗ Test failed\\n\");\n    try sailor.color.warn(stdout, \"⚠ Deprecated API\\n\");\n}\n```\n\n### Argument Parsing\n\n```zig\nvar parser = sailor.arg.Parser.init(allocator);\ndefer parser.deinit();\n\nparser.addFlag(.{\n    .long = \"output\",\n    .short = 'o',\n    .type = .string,\n    .description = \"Output file path\",\n    .required = true,\n});\n\nconst args = try parser.parse();\nconst output = args.flag(\"output\").?;\n```\n\n### Progress Bar\n\n```zig\nvar bar = try sailor.progress.Bar.init(allocator, 100);\ndefer bar.deinit();\n\nfor (0..101) |i| {\n    bar.set(i);\n    try bar.render(std.io.getStdOut().writer());\n    std.time.sleep(20 * std.time.ns_per_ms);\n}\n```\n\n### TUI Application\n\n```zig\nvar terminal = try sailor.tui.Terminal.init(allocator);\ndefer terminal.deinit();\n\nconst app = App{ .counter = 0 };\n\nwhile (app.running) {\n    try terminal.draw(app, render);\n\n    if (try terminal.pollEvent(100)) |event| {\n        switch (event) {\n            .key =\u003e |key| switch (key) {\n                .char =\u003e |c| if (c == 'q') app.running = false,\n                .ctrl_c =\u003e app.running = false,\n                else =\u003e {},\n            },\n            else =\u003e {},\n        }\n    }\n}\n```\n\nSee [examples/](examples/) for complete applications.\n\n## Development\n\n```bash\n# Build library\nzig build\n\n# Run tests (720+ tests)\nzig build test\n\n# Run examples\nzig build example -- hello\nzig build example -- counter\nzig build example -- dashboard\n\n# Cross-compile verification\nzig build -Dtarget=x86_64-linux-gnu\nzig build -Dtarget=x86_64-windows-msvc\nzig build -Dtarget=aarch64-macos\n```\n\n## Platform Support\n\n| Platform | x86_64 | ARM64 |\n|----------|--------|-------|\n| **Linux** | ✅ | ✅ |\n| **macOS** | ✅ | ✅ |\n| **Windows** | ✅ | ✅ |\n\nAll platforms are tested in CI on every commit.\n\n## Features by Version\n\n| Version | Features |\n|---------|----------|\n| **v0.1.0** | Terminal backend, styled output, argument parsing |\n| **v0.2.0** | REPL, progress indicators, table formatting |\n| **v0.3.0** | TUI core (layout, buffer, rendering) |\n| **v0.4.0** | Core widgets (Block, List, Table, Input, Tabs, etc.) |\n| **v0.5.0** | Advanced widgets (Tree, TextArea, Charts, Dialog, etc.) |\n| **v1.0.0** | Polish, theming, animation, comprehensive docs |\n| **v1.1.0** | Accessibility (screen reader hints, focus management, keyboard nav) |\n| **v1.2.0** | Layout \u0026 composition (grid layout, scrollable viewport, overlays) |\n| **v1.3.0** | Performance (render budget, lazy rendering, debug overlay) |\n| **v1.4.0** | Advanced input \u0026 forms (Select, Checkbox, RadioGroup, Form) |\n| **v1.5.0** | State management (event bus, command pattern, test utilities) |\n| **v1.6.0** | Data visualization (Heatmap, PieChart, ScatterPlot, Histogram, TimeSeries) |\n| **v1.7.0** | Advanced layout (FlexBox, viewport clipping, shadow effects) |\n| **v1.8.0** | Network \u0026 async (HttpClient, WebSocket, TaskRunner, LogViewer) |\n\n## Design Principles\n\n- **Library-first** - No global state, you control allocations\n- **Writer-based** - All output via `std.io.Writer`, never direct stdout/stderr\n- **Error-aware** - No panics in library code, explicit error handling\n- **Modular** - Use `sailor.color` without importing `sailor.tui`\n- **Cross-platform** - Platform differences handled internally\n- **Well-tested** - 720+ tests with 100% coverage of public APIs\n\n## Inspiration\n\nsailor draws inspiration from:\n- [ratatui](https://github.com/ratatui-org/ratatui) (Rust) - Widget architecture and layout system\n- [bubbletea](https://github.com/charmbracelet/bubbletea) (Go) - Event-driven TUI model\n- [colored](https://github.com/mackwic/colored) (Rust) - ANSI color API design\n\n## Contributing\n\nContributions welcome! Please:\n1. Read [CLAUDE.md](CLAUDE.md) for project structure\n2. Run `zig build test` before submitting\n3. Follow existing code style (see [docs/GUIDE.md](docs/GUIDE.md#best-practices))\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\nBuilt with ❤️ in Zig. Ship your CLI/TUI apps with **sailor**! 🚢\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyusa-imit%2Fsailor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyusa-imit%2Fsailor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyusa-imit%2Fsailor/lists"}