WIP: exec element with initial implementation

Problem is that the main application actually does not create a pty and
instead uses the current one (for better compatability for ssh based
hosting).

The current problem is the fact that the child process should not
take over (and never give back too) the input / output handling of the
current pts. Such that both applications can receive inputs accordingly
(in best case actually controlled by the main application).

.gitea/workflows/release.yaml

@@ -15,7 +15,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup zig installation
-        uses: mlugg/setup-zig@v1
+        uses: mlugg/setup-zig@v2
         with:
           version: master
       - name: Run tests

.gitea/workflows/test.yaml

@@ -14,7 +14,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup zig installation
-        uses: mlugg/setup-zig@v1
+        uses: mlugg/setup-zig@v2
         with:
           version: master
       - name: Lint check

build.zig

@@ -1,5 +1,3 @@
-const std = @import("std");
-
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
@@ -7,9 +5,12 @@ pub fn build(b: *std.Build) void {
     const Examples = enum {
         all,
         demo,
+        continuous,
         // elements:
+        alignment,
         button,
         input,
+        progress,
         scrollable,
         // layouts:
         vertical,
@@ -24,9 +25,13 @@ pub fn build(b: *std.Build) void {
     };
 
     const example = b.option(Examples, "example", "Example to build and/or run. (default: all)") orelse .all;
+    const debug_rendering = b.option(bool, "debug", "Enable debug rendering. Highlight origin's, size's, padding's, gap's, etc. (default: false)") orelse false;
+    // NOTE do not support debug rendering in release builds
+    if (debug_rendering == true and optimize != .Debug) @panic("Cannot enable debug rendering in non-debug builds.");
 
     const options = b.addOptions();
-    options.addOption(Examples, "example", example);
+    options.addOption(bool, "debug", debug_rendering);
+    const options_module = options.createModule();
 
     // dependencies
     const zg = b.dependency("zg", .{
@@ -36,163 +41,63 @@ pub fn build(b: *std.Build) void {
 
     // library
     const lib = b.addModule("zterm", .{
-        .root_source_file = b.path("src/zterm.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = optimize,
     });
     lib.addImport("code_point", zg.module("code_point"));
+    lib.addImport("build_options", options_module);
 
     //--- Examples ---
-
+    const examples = std.meta.fields(Examples);
-    // demo:
+    inline for (examples) |e| {
-    const demo = b.addExecutable(.{
+        if (@as(Examples, @enumFromInt(e.value)) == .all) continue; // skip `.all` entry
-        .name = "demo",
+        const demo = b.addExecutable(.{
-        .root_source_file = b.path("examples/demo.zig"),
+            .name = e.name,
-        .target = target,
+            .root_source_file = b.path(switch (@as(Examples, @enumFromInt(e.value))) {
-        .optimize = optimize,
+                .demo => "examples/demo.zig",
-    });
+                .continuous => "examples/continuous.zig",
-    demo.root_module.addImport("zterm", lib);
+                // elements:
-
+                .alignment => "examples/elements/alignment.zig",
-    // elements:
+                .button => "examples/elements/button.zig",
-    const button = b.addExecutable(.{
+                .input => "examples/elements/input.zig",
-        .name = "button",
+                .progress => "examples/elements/progress.zig",
-        .root_source_file = b.path("examples/elements/button.zig"),
+                .scrollable => "examples/elements/scrollable.zig",
-        .target = target,
+                // layouts:
-        .optimize = optimize,
+                .vertical => "examples/layouts/vertical.zig",
-    });
+                .horizontal => "examples/layouts/horizontal.zig",
-    button.root_module.addImport("zterm", lib);
+                .grid => "examples/layouts/grid.zig",
-
+                .mixed => "examples/layouts/mixed.zig",
-    const input = b.addExecutable(.{
+                // styles:
-        .name = "input",
+                .text => "examples/styles/text.zig",
-        .root_source_file = b.path("examples/elements/input.zig"),
+                .palette => "examples/styles/palette.zig",
-        .target = target,
+                // error handling
-        .optimize = optimize,
+                .errors => "examples/errors.zig",
-    });
+                .all => unreachable, // should never happen
-    input.root_module.addImport("zterm", lib);
+            }),
-
+            .target = target,
-    const scrollable = b.addExecutable(.{
+            .optimize = optimize,
-        .name = "scrollable",
+        });
-        .root_source_file = b.path("examples/elements/scrollable.zig"),
+        // import dependencies
-        .target = target,
+        demo.root_module.addImport("zterm", lib);
-        .optimize = optimize,
+        // mapping of user selected example to compile step
-    });
+        if (@intFromEnum(example) == e.value or example == .all) b.installArtifact(demo);
-    scrollable.root_module.addImport("zterm", lib);
+    }
-
-    // layouts:
-    const vertical = b.addExecutable(.{
-        .name = "vertical",
-        .root_source_file = b.path("examples/layouts/vertical.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    vertical.root_module.addImport("zterm", lib);
-
-    const horizontal = b.addExecutable(.{
-        .name = "horizontal",
-        .root_source_file = b.path("examples/layouts/horizontal.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    horizontal.root_module.addImport("zterm", lib);
-
-    const grid = b.addExecutable(.{
-        .name = "grid",
-        .root_source_file = b.path("examples/layouts/grid.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    grid.root_module.addImport("zterm", lib);
-
-    const mixed = b.addExecutable(.{
-        .name = "mixed",
-        .root_source_file = b.path("examples/layouts/mixed.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    mixed.root_module.addImport("zterm", lib);
-
-    // styles:
-    const palette = b.addExecutable(.{
-        .name = "palette",
-        .root_source_file = b.path("examples/styles/palette.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    palette.root_module.addImport("zterm", lib);
-
-    const text = b.addExecutable(.{
-        .name = "text",
-        .root_source_file = b.path("examples/styles/text.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    text.root_module.addImport("zterm", lib);
-
-    // error handling:
-    const errors = b.addExecutable(.{
-        .name = "errors",
-        .root_source_file = b.path("examples/errors.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    errors.root_module.addImport("zterm", lib);
-
-    // mapping of user selected example to compile step
-    const exe = switch (example) {
-        .demo => demo,
-        // elements:
-        .button => button,
-        .input => input,
-        .scrollable => scrollable,
-        // layouts:
-        .vertical => vertical,
-        .horizontal => horizontal,
-        .grid => grid,
-        .mixed => mixed,
-        // styles:
-        .text => text,
-        .palette => palette,
-        // error handling:
-        .errors => errors,
-        else => blk: {
-            b.installArtifact(button);
-            b.installArtifact(input);
-            b.installArtifact(scrollable);
-            b.installArtifact(vertical);
-            b.installArtifact(horizontal);
-            b.installArtifact(grid);
-            b.installArtifact(mixed);
-            b.installArtifact(text);
-            b.installArtifact(palette);
-            b.installArtifact(errors);
-            break :blk demo;
-        },
-    };
-    b.installArtifact(exe);
-
-    // zig build run
-    const run_cmd = b.addRunArtifact(exe);
-    run_cmd.step.dependOn(b.getInstallStep());
-    // Allow additional arguments, like this: `zig build run -- arg1 arg2 etc`
-    if (b.args) |args| run_cmd.addArgs(args);
-
-    // This creates a build step. It will be visible in the `zig build --help` menu,
-    // and can be selected like this: `zig build run`
-    // This will evaluate the `run` step rather than the default, which is "install".
-    const run_step = b.step("run", "Run the app");
-    run_step.dependOn(&run_cmd.step);
 
     // zig build test
     const lib_unit_tests = b.addTest(.{
-        .root_source_file = b.path("src/zterm.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = optimize,
     });
     lib_unit_tests.root_module.addImport("code_point", zg.module("code_point"));
     lib_unit_tests.root_module.addImport("DisplayWidth", zg.module("DisplayWidth"));
+    lib_unit_tests.root_module.addImport("build_options", options_module);
 
     const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);
 
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_lib_unit_tests.step);
 }
+
+const std = @import("std");

build.zig.zon

@@ -24,7 +24,7 @@
 
     // This is a [Semantic Version](https://semver.org/).
     // In a future version of Zig it will be used for package deduplication.
-    .version = "0.2.0",
+    .version = "0.3.0",
 
     // Tracks the earliest Zig version that the package considers to be a
     // supported use case.
@@ -37,8 +37,8 @@
     // internet connectivity.
     .dependencies = .{
         .zg = .{
-            .url = "git+https://codeberg.org/atman/zg#4a002763419a34d61dcbb1f415821b83b9bf8ddc",
+            .url = "git+https://codeberg.org/atman/zg#9427a9e53aaa29ee071f4dcb35b809a699d75aa9",
-            .hash = "1220f3e29bc40856bfc06e0ee133f814b0011c76de987d8a6a458c2f34d82708899a",
+            .hash = "zg-0.14.1-oGqU3IQ_tALZIiBN026_NTaPJqU-Upm8P_C7QED2Rzm8",
         },
     },
     .paths = .{

examples/continuous.zig

@@ -0,0 +1,245 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+/// Spinner element implementation that runs a simple animation that requires
+/// the continuous draw loop.
+const Spinner = struct {
+    counter: u8 = 0,
+    index: u8 = 0,
+
+    const map: [6]u21 = .{ '𜺎', '𜺍', '𜺇', '𜹯', '𜹿', '𜺋' };
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .content = content,
+            },
+        };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        cells[size.x + 1].cp = map[this.index];
+
+        this.counter += 1;
+        if (this.counter >= 20) {
+            this.index += 1;
+            this.index %= 6;
+            this.counter = 0;
+        }
+    }
+};
+
+const InputField = struct {
+    input: std.ArrayList(u21),
+    queue: *App.Queue,
+
+    pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
+        return .{
+            .input = .init(allocator),
+            .queue = queue,
+        };
+    }
+
+    pub fn deinit(this: @This()) void {
+        this.input.deinit();
+    }
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            .key => |key| {
+                if (key.isAscii()) try this.input.append(key.cp);
+
+                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter }))
+                    this.queue.push(.{ .accept = try this.input.toOwnedSlice() });
+
+                if (key.eql(.{ .cp = zterm.input.Backspace }))
+                    _ = this.input.pop();
+
+                if (key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
+                    _ = this.input.pop();
+            },
+            else => {},
+        }
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        if (this.input.items.len == 0) return;
+
+        const row = 1;
+        const col = 1;
+        const anchor = (row * size.x) + col;
+
+        for (this.input.items, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .black;
+            cells[anchor + idx].style.cursor = false;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+
+            if (idx == this.input.items.len - 1) cells[anchor + idx + 1].style.cursor = true;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var input_field: InputField = .init(allocator, &app.queue);
+    defer input_field.deinit();
+
+    var quit_text: QuitText = .{};
+    var spinner: Spinner = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 10 },
+        },
+    }, input_field.element()));
+
+    const nested_container: App.Container = try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, spinner.element());
+    try container.append(nested_container);
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    var framerate: u64 = 60;
+    var tick_ms: u64 = @divFloor(time.ms_per_s, framerate);
+    var next_frame_ms: u64 = 0;
+
+    // draw loop
+    draw: while (true) {
+        const now_ms: u64 = @intCast(time.milliTimestamp());
+        if (now_ms >= next_frame_ms) {
+            next_frame_ms = now_ms + tick_ms;
+        } else {
+            time.sleep((next_frame_ms - now_ms) * time.ns_per_ms);
+            next_frame_ms += tick_ms;
+        }
+
+        const len = blk: {
+            app.queue.lock();
+            defer app.queue.unlock();
+            break :blk app.queue.len();
+        };
+
+        // handle events
+        for (0..len) |_| {
+            const event = app.queue.drain() orelse break;
+            log.debug("handling event: {s}", .{@tagName(event)});
+            // pre event handling
+            switch (event) {
+                .key => |key| {
+                    log.debug("key {any}", .{key});
+                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                },
+                .accept => |input| {
+                    defer allocator.free(input);
+                    var string = try allocator.alloc(u8, input.len);
+                    defer allocator.free(string);
+                    for (0.., input) |i, char| string[i] = @intCast(char);
+                    log.debug("Accepted input '{s}'", .{string});
+                },
+                .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+                .focus => |b| {
+                    // NOTE reduce framerate in case the window is not focused and restore again when focused
+                    framerate = if (b) 60 else 15;
+                    tick_ms = @divFloor(time.ms_per_s, framerate);
+                },
+                else => {},
+            }
+
+            container.handle(event) catch |err| app.postEvent(.{
+                .err = .{
+                    .err = err,
+                    .msg = "Container Event handling failed",
+                },
+            });
+
+            // post event handling
+            switch (event) {
+                .quit => break :draw,
+                else => {},
+            }
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const time = std.time;
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {
+    accept: []u21,
+});

examples/demo.zig

@@ -1,11 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const input = zterm.input;
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit. Press ctrl+n to launch helix.";
 
@@ -15,7 +7,7 @@ const QuitText = struct {
 
     pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const y = 2;
         const x = size.x / 2 -| (text.len / 2);
@@ -36,7 +28,7 @@ pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
     // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -75,7 +67,7 @@ pub fn main() !void {
     }, .{}));
     defer box.deinit();
 
-    var scrollable: App.Scrollable = .init(box);
+    var scrollable: App.Scrollable = .init(box, .disabled);
 
     var container = try App.Container.init(allocator, .{
         .layout = .{
@@ -87,6 +79,19 @@ pub fn main() !void {
     }, quit_text.element());
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
+    var environment = try std.process.getEnvMap(allocator);
+    defer environment.deinit();
+
+    var editor: App.Exec = .init(
+        allocator,
+        &.{
+            "tty",
+        },
+        &environment,
+        &app.queue,
+    );
+    defer editor.deinit();
+
     try container.append(try App.Container.init(allocator, .{
         .border = .{
             .color = .light_blue,
@@ -95,7 +100,8 @@ pub fn main() !void {
         .size = .{
             .dim = .{ .x = 100 },
         },
-    }, .{}));
+    }, editor.element()));
+
     try container.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .blue },
         .size = .{
@@ -107,6 +113,11 @@ pub fn main() !void {
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
 
+    var process_in: std.ArrayListUnmanaged(u8) = .empty;
+    defer process_in.deinit(allocator);
+    var process_out: std.ArrayListUnmanaged(u8) = .empty;
+    defer process_out.deinit(allocator);
+
     // event loop
     while (true) {
         const event = app.nextEvent();
@@ -114,22 +125,7 @@ pub fn main() !void {
 
         // pre event handling
         switch (event) {
-            .key => |key| {
+            .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-                if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
-
-                if (key.eql(.{ .cp = 'n', .mod = .{ .ctrl = true } })) {
-                    try app.interrupt();
-                    defer app.start() catch @panic("could not start app event loop");
-                    var child = std.process.Child.init(&.{"hx"}, allocator);
-                    _ = child.spawnAndWait() catch |err| app.postEvent(.{
-                        .err = .{
-                            .err = err,
-                            .msg = "Spawning $EDITOR failed",
-                        },
-                    });
-                    continue;
-                }
-            },
             // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
@@ -149,10 +145,18 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const input = zterm.input;
+const App = zterm.App(union(enum) {});

examples/elements/alignment.zig

@@ -0,0 +1,99 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var container: App.Container = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    var quit_text: QuitText = .{};
+    const quit_container = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .blue },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
+        .size = .{
+            .dim = .{ .x = 25, .y = 5 },
+            .grow = .fixed,
+        },
+    }, quit_text.element());
+
+    var alignment: App.Alignment = .init(quit_container, .center);
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    // event loop
+    while (true) {
+        const event = app.nextEvent();
+        log.debug("received event: {s}", .{@tagName(event)});
+
+        // pre event handling
+        switch (event) {
+            .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+            else => {},
+        }
+
+        container.handle(event) catch |err| app.postEvent(.{
+            .err = .{
+                .err = err,
+                .msg = "Container Event handling failed",
+            },
+        });
+
+        // post event handling
+        switch (event) {
+            .quit => break,
+            else => {},
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/elements/button.zig

@@ -1,12 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {
-    click: [:0]const u8,
-});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -16,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -66,7 +57,7 @@ const Clickable = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = size.y / 2 -| (text.len / 2);
         const col = size.x / 2 -| (text.len / 2);
@@ -86,7 +77,7 @@ const Clickable = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -98,6 +89,8 @@ pub fn main() !void {
     var clickable: Clickable = .{ .queue = &app.queue };
     const element = clickable.element();
 
+    var button: App.Button(.accept) = .init(&app.queue, .init(.default, "Button"));
+
     var quit_text: QuitText = .{};
 
     var container = try App.Container.init(allocator, .{
@@ -107,6 +100,7 @@ pub fn main() !void {
     defer container.deinit();
 
     try container.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = .light_grey } }, element));
+    try container.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = .black } }, button.element()));
 
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
@@ -119,9 +113,8 @@ pub fn main() !void {
         // pre event handling
         switch (event) {
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            .click => |button| {
+            .click => |b| log.info("Clicked with mouse using Button: {s}", .{b}),
-                log.info("Clicked with mouse using Button: {s}", .{button});
+            .accept => log.info("Clicked built-in button using the mouse", .{}),
-            },
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
@@ -139,10 +132,20 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {
+    click: [:0]const u8,
+    accept,
+});

examples/elements/input.zig

@@ -1,12 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {
-    accept: []u21,
-});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -16,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -33,20 +24,8 @@ const QuitText = struct {
     }
 };
 
-const InputField = struct {
+const MouseDraw = struct {
-    input: std.ArrayList(u21),
+    position: ?zterm.Point = null,
-    queue: *App.Queue,
-
-    pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
-        return .{
-            .input = .init(allocator),
-            .queue = queue,
-        };
-    }
-
-    pub fn deinit(this: @This()) void {
-        this.input.deinit();
-    }
 
     pub fn element(this: *@This()) App.Element {
         return .{
@@ -61,35 +40,19 @@ const InputField = struct {
     fn handle(ctx: *anyopaque, event: App.Event) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
         switch (event) {
-            .key => |key| {
+            .mouse => |mouse| this.position = .{ .x = mouse.x, .y = mouse.y },
-                if (key.isAscii()) try this.input.append(key.cp);
+            else => this.position = null,
-
-                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter }))
-                    this.queue.push(.{ .accept = try this.input.toOwnedSlice() });
-
-                if (key.eql(.{ .cp = zterm.input.Backspace }) or key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
-                    _ = this.input.pop();
-            },
-            else => {},
         }
     }
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-        if (this.input.items.len == 0) return;
+        if (this.position) |pos| {
-
+            const idx = @as(usize, size.x) * @as(usize, pos.y) + @as(usize, pos.x);
-        const row = 1;
+            cells[idx].cp = 'x';
-        const col = 1;
+            cells[idx].style.fg = .red;
-        const anchor = (row * size.x) + col;
-
-        for (this.input.items, 0..) |cp, idx| {
-            cells[anchor + idx].style.fg = .black;
-            cells[anchor + idx].cp = cp;
-
-            // NOTE do not write over the contents of this `Container`'s `Size`
-            if (anchor + idx == cells.len - 1) break;
         }
     }
 };
@@ -97,7 +60,7 @@ const InputField = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -106,20 +69,50 @@ pub fn main() !void {
     var renderer = zterm.Renderer.Buffered.init(allocator);
     defer renderer.deinit();
 
-    var input_field: InputField = .init(allocator, &app.queue);
+    var input_field: App.Input(.accept) = .init(allocator, &app.queue, .init(.black));
     defer input_field.deinit();
 
+    var mouse_draw: MouseDraw = .{};
+    var second_mouse_draw: MouseDraw = .{};
     var quit_text: QuitText = .{};
 
-    const element = input_field.element();
-
     var container = try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .grey },
-        .layout = .{ .padding = .all(5) },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
     }, quit_text.element());
     defer container.deinit();
 
-    try container.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = .light_grey } }, element));
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 1 },
+        },
+    }, input_field.element()));
+
+    var nested_container: App.Container = try .init(allocator, .{
+        .border = .{
+            .sides = .all,
+            .color = .black,
+        },
+        .rectangle = .{ .fill = .light_grey },
+        .layout = .{
+            .separator = .{
+                .enabled = true,
+                .color = .black,
+            },
+        },
+    }, .{});
+    try nested_container.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, mouse_draw.element()));
+    try nested_container.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, second_mouse_draw.element()));
+    try container.append(nested_container);
 
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
@@ -134,7 +127,7 @@ pub fn main() !void {
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
             .accept => |input| {
                 defer allocator.free(input);
-                log.info("Accepted input {any}", .{input});
+                log.debug("Accepted input '{s}'", .{input});
             },
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
@@ -153,10 +146,21 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const Color = zterm.Color;
+
+const App = zterm.App(union(enum) {
+    accept: []u8,
+});

examples/elements/progress.zig

@@ -0,0 +1,137 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var progress_percent: u8 = 0;
+    var progress: App.Progress(.progress) = .init(&app.queue, .{
+        .percent = .{ .enabled = true },
+        .fg = .green,
+        .bg = .grey,
+    });
+    var quit_text: QuitText = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .layout = .{ .padding = .all(5) },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{}, progress.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    var framerate: u64 = 60;
+    var tick_ms: u64 = @divFloor(time.ms_per_s, framerate);
+    var next_frame_ms: u64 = 0;
+
+    var increase_progress: u64 = 10;
+
+    // Continuous drawing
+    // draw loop
+    draw: while (true) {
+        const now_ms: u64 = @intCast(time.milliTimestamp());
+        if (now_ms >= next_frame_ms) {
+            next_frame_ms = now_ms + tick_ms;
+        } else {
+            time.sleep((next_frame_ms - now_ms) * time.ns_per_ms);
+            next_frame_ms += tick_ms;
+        }
+
+        // NOTE time based progress increasion
+        increase_progress -= 1;
+        if (increase_progress == 0) {
+            increase_progress = 10;
+            progress_percent += 1;
+            if (progress_percent > 100) progress_percent = 0;
+            app.postEvent(.{ .progress = progress_percent });
+        }
+
+        const len = blk: {
+            app.queue.lock();
+            defer app.queue.unlock();
+            break :blk app.queue.len();
+        };
+
+        // handle events
+        for (0..len) |_| {
+            const event = app.queue.drain() orelse break;
+            log.debug("handling event: {s}", .{@tagName(event)});
+            // pre event handling
+            switch (event) {
+                .key => |key| {
+                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                },
+                .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+                .focus => |b| {
+                    // NOTE reduce framerate in case the window is not focused and restore again when focused
+                    framerate = if (b) 60 else 15;
+                    tick_ms = @divFloor(time.ms_per_s, framerate);
+                },
+                else => {},
+            }
+
+            container.handle(event) catch |err| app.postEvent(.{
+                .err = .{
+                    .err = err,
+                    .msg = "Container Event handling failed",
+                },
+            });
+
+            // post event handling
+            switch (event) {
+                .quit => break :draw,
+                else => {},
+            }
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const time = std.time;
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {
+    progress: u8,
+});

examples/elements/scrollable.zig

@@ -1,11 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const input = zterm.input;
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -15,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -44,7 +36,7 @@ const HelloWorldText = packed struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = size.y / 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -65,7 +57,7 @@ pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
     // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer {
         const deinit_status = gpa.deinit();
         if (deinit_status == .leak) {
@@ -156,10 +148,10 @@ pub fn main() !void {
     defer container.deinit();
 
     // place empty container containing the element of the scrollable Container.
-    var scrollable_top: App.Scrollable = .init(top_box);
+    var scrollable_top: App.Scrollable = .init(top_box, .enabled(.grey));
     try container.append(try App.Container.init(allocator, .{}, scrollable_top.element()));
 
-    var scrollable_bottom: App.Scrollable = .init(bottom_box);
+    var scrollable_bottom: App.Scrollable = .init(bottom_box, .enabled(.white));
     try container.append(try App.Container.init(allocator, .{}, scrollable_bottom.element()));
 
     try app.start();
@@ -190,10 +182,18 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const input = zterm.input;
+const App = zterm.App(union(enum) {});

examples/errors.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -40,7 +33,7 @@ const InfoText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -75,7 +68,7 @@ const ErrorNotification = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         if (this.msg) |msg| {
             const row = size.y -| 2;
@@ -99,7 +92,7 @@ const ErrorNotification = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -150,10 +143,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/layouts/grid.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -106,10 +99,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/layouts/horizontal.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -98,10 +91,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/layouts/mixed.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -114,10 +107,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/layouts/vertical.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -97,10 +90,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/styles/palette.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -34,7 +27,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -60,10 +53,10 @@ pub fn main() !void {
     defer box.deinit();
 
     inline for (std.meta.fields(zterm.Color)) |field| {
-        if (comptime field.value == 0) continue; // zterm.Color.default == 0 -> skip
+        if (field.value == 0) continue; // zterm.Color.default == 0 -> skip
         try box.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = @enumFromInt(field.value) } }, .{}));
     }
-    var scrollable: App.Scrollable = .init(box);
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -93,10 +86,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

examples/styles/text.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -39,20 +32,20 @@ const TextStyles = struct {
     }
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
-        @setEvalBranchQuota(50000);
+        @setEvalBranchQuota(10000);
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         var row: usize = 0;
         var col: usize = 0;
 
         // Color
         inline for (std.meta.fields(zterm.Color)) |bg_field| {
-            if (comptime bg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
+            if (bg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
 
             inline for (std.meta.fields(zterm.Color)) |fg_field| {
-                if (comptime fg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
+                if (fg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
-                if (comptime fg_field.value == bg_field.value) continue;
+                if (fg_field.value == bg_field.value) continue;
 
                 // witouth any emphasis
                 for (text) |cp| {
@@ -64,7 +57,7 @@ const TextStyles = struct {
 
                 // emphasis (no combinations)
                 inline for (std.meta.fields(zterm.Style.Emphasis)) |emp_field| {
-                    if (comptime emp_field.value == 0) continue; // zterm.Style.Emphasis.reset == 0 -> skip
+                    if (emp_field.value == 0) continue; // zterm.Style.Emphasis.reset == 0 -> skip
                     const emphasis: zterm.Style.Emphasis = @enumFromInt(emp_field.value);
 
                     for (text) |cp| {
@@ -85,7 +78,7 @@ const TextStyles = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -118,7 +111,7 @@ pub fn main() !void {
     }, text_styles.element());
     defer box.deinit();
 
-    var scrollable: App.Scrollable = .init(box);
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -148,10 +141,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         container.reposition(.{});
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }
 }
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

src/app.zig

@@ -1,19 +1,4 @@
 //! Application type for TUI-applications
-const std = @import("std");
-const code_point = @import("code_point");
-const event = @import("event.zig");
-const input = @import("input.zig");
-const terminal = @import("terminal.zig");
-const queue = @import("queue.zig");
-
-const mergeTaggedUnions = event.mergeTaggedUnions;
-const isTaggedUnion = event.isTaggedUnion;
-
-const Mouse = input.Mouse;
-const Key = input.Key;
-const Point = @import("point.zig").Point;
-
-const log = std.log.scoped(.app);
 
 /// Create the App Type with the associated user events _E_ which describes
 /// an tagged union for all the user events that can be send through the
@@ -39,23 +24,21 @@ pub fn App(comptime E: type) type {
         @compileError("Provided user event `E` for `App(comptime E: type)` is not of type `union(enum)`.");
     }
     return struct {
-        pub const Event = mergeTaggedUnions(event.SystemEvent, E);
-        pub const Container = @import("container.zig").Container(Event);
-        const element = @import("element.zig");
-        pub const Element = element.Element(Event);
-        pub const Scrollable = element.Scrollable(Event);
-        pub const Exec = element.Exec(Event, Queue);
-        pub const Queue = queue.Queue(Event, 256);
-
         queue: Queue,
-        thread: ?std.Thread = null,
+        thread: ?Thread = null,
-        quit_event: std.Thread.ResetEvent,
+        quit_event: Thread.ResetEvent,
-        termios: ?std.posix.termios = null,
+        termios: ?posix.termios = null,
+        winch_registered: bool = false,
 
-        pub const SignalHandler = struct {
+        // global variable for the registered handler for WINCH
-            context: *anyopaque,
+        var handler_ctx: *anyopaque = undefined;
-            callback: *const fn (context: *anyopaque) void,
+        /// registered WINCH handler to report resize events
-        };
+        fn handleWinch(_: c_int) callconv(.C) void {
+            const this: *@This() = @ptrCast(@alignCast(handler_ctx));
+            // NOTE this does not have to be done if in-band resize events are supported
+            // -> the signal might not work correctly when hosting the application over ssh!
+            this.postEvent(.resize);
+        }
 
         pub const init: @This() = .{
             .queue = .{},
@@ -68,10 +51,21 @@ pub fn App(comptime E: type) type {
             // post init event (as the very first element to be in the queue - event loop)
             this.postEvent(.init);
 
-            this.quit_event.reset();
+            if (!this.winch_registered) {
-            this.thread = try std.Thread.spawn(.{}, @This().run, .{this});
+                handler_ctx = this;
+                var act = posix.Sigaction{
+                    .handler = .{ .handler = handleWinch },
+                    .mask = posix.sigemptyset(),
+                    .flags = 0,
+                };
+                posix.sigaction(posix.SIG.WINCH, &act, null);
+                this.winch_registered = true;
+            }
 
-            var termios: std.posix.termios = undefined;
+            this.quit_event.reset();
+            this.thread = try Thread.spawn(.{}, @This().run, .{this});
+
+            var termios: posix.termios = undefined;
             try terminal.enableRawMode(&termios);
             if (this.termios) |_| {} else this.termios = termios;
 
@@ -169,6 +163,9 @@ pub fn App(comptime E: type) type {
                                         // Legacy keys
                                         // CSI {ABCDEFHPQS}
                                         // CSI 1 ; modifier:event_type {ABCDEFHPQS}
+                                        var field_iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        _ = field_iter.next(); // skip first field
+
                                         const key: Key = .{
                                             .cp = switch (final) {
                                                 'A' => input.Up,
@@ -182,44 +179,79 @@ pub fn App(comptime E: type) type {
                                                 'Q' => input.F2,
                                                 'R' => input.F3,
                                                 'S' => input.F4,
-                                                else => unreachable, // switch case prevents in this case form ever happening
+                                                else => unreachable,
+                                            },
+                                            .mod = blk: {
+                                                // modifier_mask:event_type
+                                                var mod: Key.Modifier = .{};
+                                                const field_buf = field_iter.next() orelse break :blk mod;
+                                                var param_iter = std.mem.splitScalar(u8, field_buf, ':');
+                                                const modifier_buf = param_iter.next() orelse unreachable;
+                                                const modifier_mask = fmt.parseUnsigned(u8, modifier_buf, 10) catch break :blk mod;
+                                                if ((modifier_mask -| 1) & 1 != 0) mod.shift = true;
+                                                if ((modifier_mask -| 1) & 2 != 0) mod.alt = true;
+                                                if ((modifier_mask -| 1) & 4 != 0) mod.ctrl = true;
+                                                break :blk mod;
                                             },
                                         };
                                         this.postEvent(.{ .key = key });
                                     },
+                                    'Z' => this.postEvent(.{ .key = .{ .cp = input.Tab, .mod = .{ .shift = true } } }),
                                     '~' => {
                                         // Legacy keys
                                         // CSI number ~
                                         // CSI number ; modifier ~
                                         // CSI number ; modifier:event_type ; text_as_codepoint ~
-                                        var field_iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        var field_iter = mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
-                                        const number_buf = field_iter.next() orelse unreachable; // always will have one field
-                                        const number = std.fmt.parseUnsigned(u16, number_buf, 10) catch break;
 
                                         const key: Key = .{
-                                            .cp = switch (number) {
+                                            .cp = blk: {
-                                                2 => input.Insert,
+                                                const number_buf = field_iter.next() orelse unreachable; // always will have one field
-                                                3 => input.Delete,
+                                                const number = fmt.parseUnsigned(u16, number_buf, 10) catch break;
-                                                5 => input.PageUp,
+                                                break :blk switch (number) {
-                                                6 => input.PageDown,
+                                                    2 => input.Insert,
-                                                7 => input.Home,
+                                                    3 => input.Delete,
-                                                8 => input.End,
+                                                    5 => input.PageUp,
-                                                11 => input.F1,
+                                                    6 => input.PageDown,
-                                                12 => input.F2,
+                                                    7 => input.Home,
-                                                13 => input.F3,
+                                                    8 => input.End,
-                                                14 => input.F4,
+                                                    11 => input.F1,
-                                                15 => input.F5,
+                                                    12 => input.F2,
-                                                17 => input.F6,
+                                                    13 => input.F3,
-                                                18 => input.F7,
+                                                    14 => input.F4,
-                                                19 => input.F8,
+                                                    15 => input.F5,
-                                                20 => input.F9,
+                                                    17 => input.F6,
-                                                21 => input.F10,
+                                                    18 => input.F7,
-                                                23 => input.F11,
+                                                    19 => input.F8,
-                                                24 => input.F12,
+                                                    20 => input.F9,
-                                                // 200 => return .{ .event = .paste_start, .n = sequence.len },
+                                                    21 => input.F10,
-                                                // 201 => return .{ .event = .paste_end, .n = sequence.len },
+                                                    23 => input.F11,
-                                                57427 => input.KpBegin,
+                                                    24 => input.F12,
-                                                else => unreachable,
+                                                    25 => input.F13,
+                                                    26 => input.F14,
+                                                    28 => input.F15,
+                                                    29 => input.F16,
+                                                    31 => input.F17,
+                                                    32 => input.F18,
+                                                    33 => input.F19,
+                                                    34 => input.F20,
+                                                    // 200 => return .{ .event = .paste_start, .n = sequence.len },
+                                                    // 201 => return .{ .event = .paste_end, .n = sequence.len },
+                                                    57399...57454 => |code| code,
+                                                    else => unreachable,
+                                                };
+                                            },
+                                            .mod = blk: {
+                                                // modifier_mask:event_type
+                                                var mod: Key.Modifier = .{};
+                                                const field_buf = field_iter.next() orelse break :blk mod;
+                                                var param_iter = std.mem.splitScalar(u8, field_buf, ':');
+                                                const modifier_buf = param_iter.next() orelse unreachable;
+                                                const modifier_mask = fmt.parseUnsigned(u8, modifier_buf, 10) catch break :blk mod;
+                                                if ((modifier_mask -| 1) & 1 != 0) mod.shift = true;
+                                                if ((modifier_mask -| 1) & 2 != 0) mod.alt = true;
+                                                if ((modifier_mask -| 1) & 4 != 0) mod.ctrl = true;
+                                                break :blk mod;
                                             },
                                         };
                                         this.postEvent(.{ .key = key });
@@ -228,14 +260,14 @@ pub fn App(comptime E: type) type {
                                     'I' => this.postEvent(.{ .focus = true }),
                                     'O' => this.postEvent(.{ .focus = false }),
                                     'M', 'm' => {
-                                        std.debug.assert(sequence.len >= 4);
+                                        assert(sequence.len >= 4);
                                         if (sequence[2] != '<') break;
 
-                                        const delim1 = std.mem.indexOfScalarPos(u8, sequence, 3, ';') orelse break;
+                                        const delim1 = mem.indexOfScalarPos(u8, sequence, 3, ';') orelse break;
-                                        const button_mask = std.fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
+                                        const button_mask = fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
-                                        const delim2 = std.mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
+                                        const delim2 = mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
-                                        const px = std.fmt.parseUnsigned(u16, sequence[delim1 + 1 .. delim2], 10) catch break;
+                                        const px = fmt.parseUnsigned(u16, sequence[delim1 + 1 .. delim2], 10) catch break;
-                                        const py = std.fmt.parseUnsigned(u16, sequence[delim2 + 1 .. sequence.len - 1], 10) catch break;
+                                        const py = fmt.parseUnsigned(u16, sequence[delim2 + 1 .. sequence.len - 1], 10) catch break;
 
                                         const mouse_bits = packed struct {
                                             const motion: u8 = 0b00100000;
@@ -256,12 +288,8 @@ pub fn App(comptime E: type) type {
                                             .x = px -| 1,
                                             .y = py -| 1,
                                             .kind = blk: {
-                                                if (motion and button != Mouse.Button.none) {
+                                                if (motion and button != Mouse.Button.none) break :blk .drag;
-                                                    break :blk .drag;
+                                                if (motion and button == Mouse.Button.none) break :blk .motion;
-                                                }
-                                                if (motion and button == Mouse.Button.none) {
-                                                    break :blk .motion;
-                                                }
                                                 if (sequence[sequence.len - 1] == 'm') break :blk .release;
                                                 break :blk .press;
                                             },
@@ -275,14 +303,14 @@ pub fn App(comptime E: type) type {
                                         // Device Status Report
                                         // CSI Ps n
                                         // CSI ? Ps n
-                                        std.debug.assert(sequence.len >= 3);
+                                        assert(sequence.len >= 3);
                                     },
                                     't' => {
                                         // XTWINOPS
                                         // Split first into fields delimited by ';'
-                                        var iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        var iter = mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
                                         const ps = iter.first();
-                                        if (std.mem.eql(u8, "48", ps)) {
+                                        if (mem.eql(u8, "48", ps)) {
                                             // in band window resize
                                             // CSI 48 ; height ; width ; height_pix ; width_pix t
                                             const width_char = iter.next() orelse break;
@@ -290,9 +318,10 @@ pub fn App(comptime E: type) type {
 
                                             _ = width_char;
                                             _ = height_char;
+                                            this.postEvent(.resize);
                                             // this.postEvent(.{ .size = .{
-                                            //     .x = std.fmt.parseUnsigned(u16, width_char, 10) catch break,
+                                            //     .x = fmt.parseUnsigned(u16, width_char, 10) catch break,
-                                            //     .y = std.fmt.parseUnsigned(u16, height_char, 10) catch break,
+                                            //     .y = fmt.parseUnsigned(u16, height_char, 10) catch break,
                                             // } });
                                         }
                                     },
@@ -308,9 +337,29 @@ pub fn App(comptime E: type) type {
                                     else => {},
                                 }
                             },
+                            0x50 => {
+                                // DCS
+                            },
+                            0x58 => {
+                                // SOS
+                            },
+                            0x5D => {
+                                // OSC
+                            },
                             // TODO parse corresponding codes
-                            // 0x5B => parseCsi(input, &self.buf), // CSI see https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig
+                            0x5F => {
-                            else => {},
+                                // APC
+                                // parse for kitty graphics capabilities
+                            },
+                            else => {
+                                // alt + <char> keypress
+                                this.postEvent(.{
+                                    .key = .{
+                                        .cp = buf[1],
+                                        .mod = .{ .alt = true },
+                                    },
+                                });
+                            },
                         }
                     } else {
                         const b = buf[0];
@@ -318,10 +367,11 @@ pub fn App(comptime E: type) type {
                             0x00 => .{ .cp = '@', .mod = .{ .ctrl = true } },
                             0x08 => .{ .cp = input.Backspace },
                             0x09 => .{ .cp = input.Tab },
-                            0x0a, 0x0d => .{ .cp = input.Enter },
+                            0x0a => .{ .cp = 'j', .mod = .{ .ctrl = true } },
+                            0x0d => .{ .cp = input.Enter },
                             0x01...0x07, 0x0b...0x0c, 0x0e...0x1a => .{ .cp = b + 0x60, .mod = .{ .ctrl = true } },
                             0x1b => escape: {
-                                std.debug.assert(read_bytes == 1);
+                                assert(read_bytes == 1);
                                 break :escape .{ .cp = input.Escape };
                             },
                             0x7f => .{ .cp = input.Backspace },
@@ -338,5 +388,55 @@ pub fn App(comptime E: type) type {
                 break;
             }
         }
+
+        pub fn panic_handler(msg: []const u8, _: ?*std.builtin.StackTrace, ret_addr: ?usize) noreturn {
+            terminal.disableMouseSupport() catch {};
+            terminal.exitAltScreen() catch {};
+            terminal.showCursor() catch {};
+            var termios: posix.termios = .{
+                .iflag = .{},
+                .lflag = .{},
+                .cflag = .{},
+                .oflag = .{},
+                .cc = undefined,
+                .line = 0,
+                .ispeed = undefined,
+                .ospeed = undefined,
+            };
+            terminal.disableRawMode(&termios) catch {};
+            terminal.restoreScreen() catch {};
+            std.debug.defaultPanic(msg, ret_addr);
+        }
+
+        const element = @import("element.zig");
+        pub const Event = mergeTaggedUnions(event.SystemEvent, E);
+        pub const Container = @import("container.zig").Container(Event);
+        pub const Element = element.Element(Event);
+        pub const Alignment = element.Alignment(Event);
+        pub const Button = element.Button(Event, Queue);
+        pub const Exec = element.Exec(Event, Queue);
+        pub const Input = element.Input(Event, Queue);
+        pub const Progress = element.Progress(Event, Queue);
+        pub const Scrollable = element.Scrollable(Event);
+        pub const Queue = queue.Queue(Event, 256);
     };
 }
+
+const log = std.log.scoped(.app);
+
+const std = @import("std");
+const mem = std.mem;
+const fmt = std.fmt;
+const posix = std.posix;
+const Thread = std.Thread;
+const assert = std.debug.assert;
+const code_point = @import("code_point");
+const event = @import("event.zig");
+const input = @import("input.zig");
+const terminal = @import("terminal.zig");
+const queue = @import("queue.zig");
+const mergeTaggedUnions = event.mergeTaggedUnions;
+const isTaggedUnion = event.isTaggedUnion;
+const Mouse = input.Mouse;
+const Key = input.Key;
+const Point = @import("point.zig").Point;

src/cell.zig

@@ -1,11 +1,8 @@
-const std = @import("std");
+//! Cell type containing content and formatting for each character in the terminal screen.
-const Style = @import("style.zig");
 
-pub const Cell = @This();
-
-style: Style = .{ .emphasis = &.{} },
 // TODO embrace `zg` dependency more due to utf-8 encoding
 cp: u21 = ' ',
+style: Style = .{ .emphasis = &.{} },
 
 pub fn eql(this: Cell, other: Cell) bool {
     return this.cp == other.cp and this.style.eql(other.style);
@@ -20,6 +17,10 @@ pub fn value(this: Cell, writer: anytype) !void {
     try this.style.value(writer, this.cp);
 }
 
+const std = @import("std");
+const Style = @import("style.zig");
+const Cell = @This();
+
 test "ascii styled text" {
     const cells: [4]Cell = .{
         .{ .cp = 'Y', .style = .{ .fg = .green, .bg = .grey, .emphasis = &.{} } },

src/color.zig

@@ -1,5 +1,3 @@
-const std = @import("std");
-
 pub const Color = enum(u8) {
     default = 0,
     black = 16,
@@ -25,16 +23,19 @@ pub const Color = enum(u8) {
     pub inline fn write(this: Color, writer: anytype, comptime coloring: enum { fg, bg, ul }) !void {
         if (this == .default) {
             switch (coloring) {
-                .fg => try std.fmt.format(writer, "39", .{}),
+                .fg => try format(writer, "39", .{}),
-                .bg => try std.fmt.format(writer, "49", .{}),
+                .bg => try format(writer, "49", .{}),
-                .ul => try std.fmt.format(writer, "59", .{}),
+                .ul => try format(writer, "59", .{}),
             }
         } else {
             switch (coloring) {
-                .fg => try std.fmt.format(writer, "38;5;{d}", .{@intFromEnum(this)}),
+                .fg => try format(writer, "38;5;{d}", .{@intFromEnum(this)}),
-                .bg => try std.fmt.format(writer, "48;5;{d}", .{@intFromEnum(this)}),
+                .bg => try format(writer, "48;5;{d}", .{@intFromEnum(this)}),
-                .ul => try std.fmt.format(writer, "58;5;{d}", .{@intFromEnum(this)}),
+                .ul => try format(writer, "58;5;{d}", .{@intFromEnum(this)}),
             }
         }
     }
 };
+
+const std = @import("std");
+const format = std.fmt.format;

src/container.zig

@@ -1,21 +1,5 @@
-const std = @import("std");
-
-const isTaggedUnion = @import("event.zig").isTaggedUnion;
-
-const Cell = @import("cell.zig");
-const Color = @import("color.zig").Color;
-const Point = @import("point.zig").Point;
-const Style = @import("style.zig");
-const Error = @import("error.zig").Error;
-
-const log = std.log.scoped(.container);
-
 /// Border configuration struct
 pub const Border = packed struct {
-    // corners:
-    const rounded_border: [6]u21 = .{ '╭', '─', '╮', '│', '╰', '╯' };
-    const squared_border: [6]u21 = .{ '┌', '─', '┐', '│', '└', '┘' };
-
     /// Color to use for the border
     color: Color = .default,
     /// Configure the corner type to be used for the border
@@ -39,13 +23,12 @@ pub const Border = packed struct {
     } = .{},
 
     pub fn content(this: @This(), cells: []Cell, size: Point) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-        const frame = switch (this.corners) {
+        const frame: [6]u21 = switch (this.corners) {
-            .rounded => Border.rounded_border,
+            .rounded => .{ '╭', '─', '╮', '│', '╰', '╯' },
-            .squared => Border.squared_border,
+            .squared => .{ '┌', '─', '┐', '│', '└', '┘' },
         };
-        std.debug.assert(frame.len == 6);
 
         // render top and bottom border
         if (this.sides.top or this.sides.bottom) {
@@ -155,13 +138,20 @@ pub const Rectangle = packed struct {
 
     // NOTE caller owns `Cells` slice and ensures that `cells.len == size.x * size.y`
     pub fn content(this: @This(), cells: []Cell, size: Point) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         for (0..size.y) |row| {
             for (0..size.x) |col| {
                 cells[(row * size.x) + col].style.bg = this.fill;
             }
         }
+
+        // DEBUG render corresponding beginning of the rectangle for this `Container` *red*
+        if (comptime build_options.debug) {
+            cells[0].style.fg = .red;
+            cells[0].style.bg = .black;
+            cells[0].cp = 'r'; // 'r' for *rectangle*
+        }
     }
 
     test "fill color overwrite parent fill" {
@@ -205,6 +195,33 @@ pub const Rectangle = packed struct {
         }, &container, @import("test/container/rectangle_with_parent_padding.zon"));
     }
 
+    test "fill color padding to show parent fill (negative padding)" {
+        const event = @import("event.zig");
+        const testing = @import("testing.zig");
+
+        var container: Container(event.SystemEvent) = try .init(std.testing.allocator, .{
+            .layout = .{
+                .padding = .{
+                    .top = -18,
+                    .bottom = -18,
+                    .left = -28,
+                    .right = -28,
+                },
+            },
+            .rectangle = .{ .fill = .green },
+        }, .{});
+        try container.append(try .init(std.testing.allocator, .{
+            .rectangle = .{ .fill = .white },
+        }, .{}));
+        try container.append(try .init(std.testing.allocator, .{}, .{}));
+        defer container.deinit();
+
+        try testing.expectContainerScreen(.{
+            .y = 20,
+            .x = 30,
+        }, &container, @import("test/container/rectangle_with_parent_padding.zon"));
+    }
+
     test "fill color spacer with padding" {
         const event = @import("event.zig");
         const testing = @import("testing.zig");
@@ -299,32 +316,27 @@ pub const Rectangle = packed struct {
 
 /// Layout configuration struct
 pub const Layout = packed struct {
-    // separator.line:
-    const line: [2]u21 = .{ '│', '─' };
-    const dotted: [2]u21 = .{ '┆', '┄' };
-    const double: [2]u21 = .{ '║', '═' };
-
     /// control the direction in which child elements are laid out
     direction: enum(u1) { horizontal, vertical } = .horizontal,
     /// Padding outside of the child elements
     padding: packed struct {
-        top: u16 = 0,
+        top: i16 = 0,
-        bottom: u16 = 0,
+        bottom: i16 = 0,
-        left: u16 = 0,
+        left: i16 = 0,
-        right: u16 = 0,
+        right: i16 = 0,
 
         /// Create a padding with equivalent padding in all four directions.
-        pub fn all(padding: u16) @This() {
+        pub fn all(padding: i16) @This() {
             return .{ .top = padding, .bottom = padding, .left = padding, .right = padding };
         }
 
         /// Create a padding with equivalent padding in the left and right directions; others directions remain the default value.
-        pub fn horizontal(padding: u16) @This() {
+        pub fn horizontal(padding: i16) @This() {
             return .{ .left = padding, .right = padding };
         }
 
         /// Create a padding with equivalent padding in the top and bottom directions; others directions remain the default value.
-        pub fn vertical(padding: u16) @This() {
+        pub fn vertical(padding: i16) @This() {
             return .{ .top = padding, .bottom = padding };
         }
     } = .{},
@@ -341,14 +353,19 @@ pub const Layout = packed struct {
         } = .line,
     } = .{},
 
+    /// Calculate the absolute offset for the provided `padding` if it is negative to get the absolute padding for the given `size`.
+    pub fn getAbsolutePadding(padding: i16, size: u16) u16 {
+        return if (padding >= 0) @intCast(padding) else size -| @as(u16, @intCast(-padding));
+    }
+
     pub fn content(this: @This(), comptime C: type, cells: []Cell, origin: Point, size: Point, children: []const C) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         if (this.separator.enabled and children.len > 1) {
             const line_cps: [2]u21 = switch (this.separator.line) {
-                .line => line,
+                .line => .{ '│', '─' },
-                .dotted => dotted,
+                .dotted => .{ '┆', '┄' },
-                .double => double,
+                .double => .{ '║', '═' },
             };
             const gap: u16 = (this.gap + 1) / 2;
 
@@ -371,8 +388,11 @@ pub const Layout = packed struct {
                 }
 
                 // DEBUG render corresponding beginning of the separator for this `Container` *red*
-                // cells[anchor].style.fg = .red;
+                if (comptime build_options.debug) {
-                // cells[anchor].style.bg = .red;
+                    cells[anchor].style.fg = .red;
+                    cells[anchor].style.bg = .black;
+                    cells[anchor].cp = 's'; // 's' for *separator*
+                }
             }
         }
     }
@@ -573,11 +593,12 @@ pub fn Container(comptime Event: type) type {
 
     const Element = @import("element.zig").Element(Event);
     return struct {
-        allocator: std.mem.Allocator,
+        allocator: Allocator,
         origin: Point,
         size: Point,
         properties: Properties,
         element: Element,
+        // TODO this should be renamed to `children`
         elements: std.ArrayList(@This()),
 
         /// Properties for each `Container` to configure their layout,
@@ -591,7 +612,7 @@ pub fn Container(comptime Event: type) type {
         };
 
         pub fn init(
-            allocator: std.mem.Allocator,
+            allocator: Allocator,
             properties: Properties,
             element: Element,
         ) !@This() {
@@ -605,10 +626,8 @@ pub fn Container(comptime Event: type) type {
             };
         }
 
-        pub fn deinit(this: *@This()) void {
+        pub fn deinit(this: *const @This()) void {
-            for (this.elements.items) |*element| {
+            for (this.elements.items) |*element| element.deinit();
-                element.deinit();
-            }
             this.elements.deinit();
         }
 
@@ -622,8 +641,8 @@ pub fn Container(comptime Event: type) type {
             this.element.reposition(origin);
 
             var offset = origin.add(.{
-                .x = layout.padding.left,
+                .x = Layout.getAbsolutePadding(layout.padding.left, this.size.x),
-                .y = layout.padding.top,
+                .y = Layout.getAbsolutePadding(layout.padding.top, this.size.y),
             });
 
             const sides = this.properties.border.sides;
@@ -655,8 +674,8 @@ pub fn Container(comptime Event: type) type {
             };
 
             if (this.elements.items.len > 0) switch (layout.direction) {
-                .horizontal => size.x += layout.padding.left + layout.padding.right,
+                .horizontal => size.x += Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x),
-                .vertical => size.y += layout.padding.top + layout.padding.bottom,
+                .vertical => size.y += Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y),
             };
 
             const sides = this.properties.border.sides;
@@ -697,25 +716,23 @@ pub fn Container(comptime Event: type) type {
                     .y = @max(size.y, this.properties.size.dim.y),
                 },
             };
-            log.debug("fit_size returning: {any}", .{this.size});
             return this.size;
         }
 
         /// growable implicitly requires the root `Container` to have a set a size property to the size of the available terminal screen
         fn grow_resize(this: *@This(), max_size: Point) void {
-            log.debug("grow_size: {any}", .{this.size});
             const layout = this.properties.layout;
             var remainder = switch (layout.direction) {
-                .horizontal => max_size.x -| (layout.padding.left + layout.padding.right),
+                .horizontal => max_size.x -| (Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x)),
-                .vertical => max_size.y -| (layout.padding.top + layout.padding.bottom),
+                .vertical => max_size.y -| (Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y)),
             };
             remainder -|= layout.gap * @as(u16, @truncate(this.elements.items.len -| 1));
 
             if (layout.separator.enabled) remainder -|= @as(u16, @truncate(this.elements.items.len -| 1));
 
             var available = switch (layout.direction) {
-                .horizontal => max_size.y -| (layout.padding.top + layout.padding.bottom),
+                .horizontal => max_size.y -| (Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y)),
-                .vertical => max_size.x -| (layout.padding.left + layout.padding.right),
+                .vertical => max_size.x -| (Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x)),
             };
 
             const sides = this.properties.border.sides;
@@ -788,6 +805,11 @@ pub fn Container(comptime Event: type) type {
                 for (this.elements.items) |child| {
                     if (child.properties.size.grow == .fixed) continue;
 
+                    switch (layout.direction) {
+                        .horizontal => if (child.properties.size.grow == .vertical) continue,
+                        .vertical => if (child.properties.size.grow == .horizontal) continue,
+                    }
+
                     const size = switch (layout.direction) {
                         .horizontal => child.size.x,
                         .vertical => child.size.y,
@@ -804,10 +826,8 @@ pub fn Container(comptime Event: type) type {
 
                 size_to_correct = @min(size_to_correct, remainder / growable_children);
                 var overflow: u16 = 0;
-                if (size_to_correct == 0 and remainder > 0) {
+                if (size_to_correct == 0 and remainder > 0) overflow = remainder;
-                    // there is some overflow
+
-                    overflow = remainder;
-                }
                 for (this.elements.items) |*child| {
                     const child_size = switch (layout.direction) {
                         .horizontal => child.size.x,
@@ -817,9 +837,11 @@ pub fn Container(comptime Event: type) type {
                         switch (layout.direction) {
                             .horizontal => if (child.properties.size.grow != .vertical) {
                                 child.size.x += size_to_correct;
+                                remainder -|= size_to_correct;
                             },
                             .vertical => if (child.properties.size.grow != .horizontal) {
                                 child.size.y += size_to_correct;
+                                remainder -|= size_to_correct;
                             },
                         }
                         if (overflow > 0) {
@@ -836,7 +858,6 @@ pub fn Container(comptime Event: type) type {
                                 },
                             }
                         }
-                        remainder -|= size_to_correct;
                     }
                 }
             }
@@ -847,6 +868,7 @@ pub fn Container(comptime Event: type) type {
 
         pub fn resize(this: *@This(), size: Point) void {
             // NOTE assume that this function is only called for the root `Container`
+            this.size = size;
             const fit_size = this.fit_resize();
             // if (fit_size.y > size.y or fit_size.x > size.x) @panic("error: cannot render in available space");
             switch (this.properties.size.grow) {
@@ -864,10 +886,15 @@ pub fn Container(comptime Event: type) type {
             this.grow_resize(this.size);
         }
 
-        pub fn handle(this: *@This(), event: Event) !void {
+        pub fn handle(this: *const @This(), event: Event) !void {
             switch (event) {
                 .mouse => |mouse| if (mouse.in(this.origin, this.size)) {
-                    try this.element.handle(event);
+                    // the element receives the mouse event with relative position
+                    assert(mouse.x >= this.origin.x and mouse.y >= this.origin.y);
+                    var relative_mouse: input.Mouse = mouse;
+                    relative_mouse.x -= this.origin.x;
+                    relative_mouse.y -= this.origin.y;
+                    try this.element.handle(.{ .mouse = relative_mouse });
                     for (this.elements.items) |*element| try element.handle(event);
                 },
                 else => {
@@ -877,11 +904,12 @@ pub fn Container(comptime Event: type) type {
             }
         }
 
-        pub fn content(this: *const @This()) ![]const Cell {
+        pub fn content(this: *const @This()) ![]Cell {
             if (this.size.x == 0 or this.size.y == 0) return Error.TooSmall;
+
             const cells = try this.allocator.alloc(Cell, @as(usize, this.size.x) * @as(usize, this.size.y));
-            @memset(cells, .{});
             errdefer this.allocator.free(cells);
+            @memset(cells, .{});
 
             this.properties.layout.content(@This(), cells, this.origin, this.size, this.elements.items);
             this.properties.border.content(cells, this.size);
@@ -889,19 +917,43 @@ pub fn Container(comptime Event: type) type {
 
             try this.element.content(cells, this.size);
 
-            // DEBUG render corresponding top left corner of this `Container` *red*
+            // DEBUG render corresponding corners (except top left) of this `Container` *red*
-            // cells[0].style.fg = .red;
+            if (comptime build_options.debug) {
-            // cells[0].style.bg = .red;
+                // top right
+                cells[this.size.x -| 1].style.fg = .red;
+                cells[this.size.x -| 1].style.bg = .black;
+                cells[this.size.x -| 1].cp = 'c'; // 'c' for *container*
+                // bottom left
+                cells[this.size.x * (this.size.y -| 1)].style.fg = .red;
+                cells[this.size.x * (this.size.y -| 1)].style.bg = .black;
+                cells[this.size.x * (this.size.y -| 1)].cp = 'c'; // 'c' for *container*
+                // bottom right
+                cells[this.size.x * this.size.y -| 1].style.fg = .red;
+                cells[this.size.x * this.size.y -| 1].style.bg = .black;
+                cells[this.size.x * this.size.y -| 1].cp = 'c'; // 'c' for *container*
+            }
 
             return cells;
         }
     };
 }
 
+const log = std.log.scoped(.container);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const build_options = @import("build_options");
+const input = @import("input.zig");
+const isTaggedUnion = @import("event.zig").isTaggedUnion;
+const Cell = @import("cell.zig");
+const Color = @import("color.zig").Color;
+const Point = @import("point.zig").Point;
+const Style = @import("style.zig");
+const Error = @import("error.zig").Error;
+
 test {
-    _ = Border;
+    @import("std").testing.refAllDeclsRecursive(@This());
-    _ = Layout;
-    _ = Rectangle;
 }
 
 test "Container Fixed and Grow Size Vertical" {

src/event.zig

@@ -1,12 +1,5 @@
 //! Events which are defined by the library. They might be extended by user
 //! events. See `App` for more details about user defined events.
-const std = @import("std");
-const input = @import("input.zig");
-const terminal = @import("terminal.zig");
-
-const Key = input.Key;
-const Mouse = input.Mouse;
-const Point = @import("point.zig").Point;
 
 /// System events available to every `zterm.App`
 pub const SystemEvent = union(enum) {
@@ -15,8 +8,11 @@ pub const SystemEvent = union(enum) {
     init,
     /// Quit event to signify the end of the event loop (rendering should stop afterwards)
     quit,
+    /// Resize event to signify that the application should re-draw to resize
+    resize,
     /// Error event to notify other containers about a recoverable error
     err: struct {
+        /// actual error
         err: anyerror,
         /// associated error message
         msg: []const u8,
@@ -28,6 +24,8 @@ pub const SystemEvent = union(enum) {
     /// Focus event for mouse interaction
     /// TODO this should instead be a union with a `Size` to derive which container / element the focus meant for
     focus: bool,
+    /// Exit event for a completed `Exec` with the associated pid. Fired and handled by `Exec` `Element`s.
+    exited: std.posix.pid_t,
 };
 
 pub fn mergeTaggedUnions(comptime A: type, comptime B: type) type {
@@ -92,3 +90,10 @@ pub fn isTaggedUnion(comptime E: type) bool {
     }
     return true;
 }
+
+const std = @import("std");
+const input = @import("input.zig");
+const terminal = @import("terminal.zig");
+const Key = input.Key;
+const Mouse = input.Mouse;
+const Point = @import("point.zig").Point;

src/input.zig

@@ -1,7 +1,4 @@
 //! Input module for `zterm`. Contains structs to represent key events and mouse events.
-const std = @import("std");
-
-const Point = @import("point.zig").Point;
 
 pub const Mouse = packed struct {
     x: u16,
@@ -32,7 +29,7 @@ pub const Mouse = packed struct {
     };
 
     pub fn eql(this: @This(), other: @This()) bool {
-        return std.meta.eql(this, other);
+        return meta.eql(this, other);
     }
 
     pub fn in(this: @This(), origin: Point, size: Point) bool {
@@ -65,7 +62,7 @@ pub const Key = packed struct {
     /// }
     /// ```
     pub fn eql(this: @This(), other: @This()) bool {
-        return std.meta.eql(this, other);
+        return meta.eql(this, other);
     }
 
     // TODO might be useful to use the std.ascii stuff!
@@ -92,24 +89,25 @@ pub const Key = packed struct {
     }
 
     test "isAscii with ascii character" {
-        try std.testing.expectEqual(true, isAscii(.{ .cp = 'c' }));
+        try testing.expectEqual(true, isAscii(.{ .cp = 'c' }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .ctrl = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .ctrl = true } }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true } }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true, .ctrl = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true, .ctrl = true } }));
     }
 
     test "isAscii with non-ascii character" {
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Escape }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Escape }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Enter }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Enter, .mod = .{ .alt = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter, .mod = .{ .alt = true } }));
     }
 
     test "isAscii with excluded input.Delete" {
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Delete }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Delete }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Delete, .mod = .{ .alt = false, .ctrl = false } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Delete, .mod = .{ .alt = false, .ctrl = false } }));
     }
 };
 
+// TODO: std.ascii has the escape codes too!
 // codepoints for keys
 pub const Tab: u21 = 0x09;
 pub const Enter: u21 = 0x0D;
@@ -154,21 +152,6 @@ pub const F17: u21 = 57380;
 pub const F18: u21 = 57381;
 pub const F19: u21 = 57382;
 pub const F20: u21 = 57383;
-pub const F21: u21 = 57384;
-pub const F22: u21 = 57385;
-pub const F23: u21 = 57386;
-pub const F24: u21 = 57387;
-pub const F25: u21 = 57388;
-pub const F26: u21 = 57389;
-pub const F27: u21 = 57390;
-pub const F28: u21 = 57391;
-pub const F29: u21 = 57392;
-pub const F30: u21 = 57393;
-pub const F31: u21 = 57394;
-pub const F32: u21 = 57395;
-pub const F33: u21 = 57396;
-pub const F34: u21 = 57397;
-pub const F35: u21 = 57398;
 pub const Kp0: u21 = 57399;
 pub const Kp1: u21 = 57400;
 pub const Kp2: u21 = 57401;
@@ -225,3 +208,8 @@ pub const RightHyper: u21 = 57451;
 pub const RightMeta: u21 = 57452;
 pub const IsoLevel3Shift: u21 = 57453;
 pub const IsoLevel5Shift: u21 = 57454;
+
+const std = @import("std");
+const meta = std.meta;
+const Point = @import("point.zig").Point;
+const testing = std.testing;

src/queue.zig

@@ -1,9 +1,7 @@
 // taken from https://github.com/rockorager/libvaxis/blob/main/src/queue.zig (MIT-License)
 // with slight modifications
-const std = @import("std");
-const assert = std.debug.assert;
 
-/// Thread safe. Fixed size. Blocking push and pop.
+/// Queue implementation. Thread safe. Fixed size. Blocking push and pop. Polling through tryPop and tryPush.
 pub fn Queue(comptime T: type, comptime size: usize) type {
     return struct {
         buf: [size]T = undefined,
@@ -92,6 +90,23 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
             assert(!this.isEmptyLH());
         }
 
+        pub fn lock(this: *QueueType) void {
+            this.mutex.lock();
+        }
+
+        pub fn unlock(this: *QueueType) void {
+            this.mutex.unlock();
+        }
+
+        /// Used to efficiently drain the queue
+        pub fn drain(this: *QueueType) ?T {
+            if (this.isEmptyLH()) return null;
+
+            const result = this.buf[this.mask(this.read_index)];
+            this.read_index = this.mask2(this.read_index + 1);
+            return result;
+        }
+
         fn isEmptyLH(this: QueueType) bool {
             return this.write_index == this.read_index;
         }
@@ -116,7 +131,7 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
         }
 
         /// Returns the length
-        fn len(this: QueueType) usize {
+        pub fn len(this: QueueType) usize {
             const wrap_offset = 2 * this.buf.len *
                 @intFromBool(this.write_index < this.read_index);
             const adjusted_write_index = this.write_index + wrap_offset;
@@ -135,8 +150,12 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
     };
 }
 
+const std = @import("std");
 const testing = std.testing;
+const assert = std.debug.assert;
+const Thread = std.Thread;
 const cfg = Thread.SpawnConfig{ .allocator = testing.allocator };
+
 test "Queue: simple push / pop" {
     var queue: Queue(u8, 16) = .{};
     queue.push(1);
@@ -146,7 +165,6 @@ test "Queue: simple push / pop" {
     try testing.expectEqual(2, queue.pop());
 }
 
-const Thread = std.Thread;
 fn testPushPop(q: *Queue(u8, 2)) !void {
     q.push(3);
     try testing.expectEqual(2, q.pop());
@@ -199,7 +217,7 @@ fn sleepyPop(q: *Queue(u8, 2)) !void {
     try Thread.yield();
     std.time.sleep(std.time.ns_per_s);
     // Finally, let that other thread go.
-    try std.testing.expectEqual(1, q.pop());
+    try testing.expectEqual(1, q.pop());
 
     // This won't continue until the other thread has had a chance to
     // put at least one item in the queue.
@@ -218,7 +236,7 @@ fn sleepyPop(q: *Queue(u8, 2)) !void {
     std.time.sleep(std.time.ns_per_s / 2);
 
     // Pop that thing and we're done.
-    try std.testing.expectEqual(2, q.pop());
+    try testing.expectEqual(2, q.pop());
 }
 
 test "Fill, block, fill, block" {
@@ -238,15 +256,15 @@ test "Fill, block, fill, block" {
 
     // Just to make sure the sleeps are yielding to this thread, make
     // sure it took at least 900ms to do the push.
-    try std.testing.expect(then - now > 900);
+    try testing.expect(then - now > 900);
 
     // This should block again, waiting for the other thread.
     queue.push(4);
 
     // And once that push has gone through, the other thread's done.
     thread.join();
-    try std.testing.expectEqual(3, queue.pop());
+    try testing.expectEqual(3, queue.pop());
-    try std.testing.expectEqual(4, queue.pop());
+    try testing.expectEqual(4, queue.pop());
 }
 
 fn sleepyPush(q: *Queue(u8, 1)) !void {
@@ -284,8 +302,8 @@ test "Drain, block, drain, block" {
 
     var queue: Queue(u8, 1) = .{};
     const thread = try Thread.spawn(cfg, sleepyPush, .{&queue});
-    try std.testing.expectEqual(1, queue.pop());
+    try testing.expectEqual(1, queue.pop());
-    try std.testing.expectEqual(2, queue.pop());
+    try testing.expectEqual(2, queue.pop());
     thread.join();
 }
 

src/render.zig

@@ -1,18 +1,14 @@
-const std = @import("std");
+//! Renderer for `zterm`.
-const terminal = @import("terminal.zig");
-
-const Cell = @import("cell.zig");
-const Point = @import("point.zig").Point;
 
 /// Double-buffered intermediate rendering pipeline
 pub const Buffered = struct {
-    allocator: std.mem.Allocator,
+    allocator: Allocator,
     created: bool,
     size: Point,
     screen: []Cell,
     virtual_screen: []Cell,
 
-    pub fn init(allocator: std.mem.Allocator) @This() {
+    pub fn init(allocator: Allocator) @This() {
         return .{
             .allocator = allocator,
             .created = false,
@@ -29,9 +25,9 @@ pub const Buffered = struct {
         }
     }
 
-    pub fn resize(this: *@This()) !void {
+    pub fn resize(this: *@This()) !Point {
         const size = terminal.getTerminalSize();
-        if (std.meta.eql(this.size, size)) return;
+        if (meta.eql(this.size, size)) return this.size;
 
         this.size = size;
         const n = @as(usize, this.size.x) * @as(usize, this.size.y);
@@ -52,6 +48,7 @@ pub const Buffered = struct {
             @memset(this.virtual_screen, .{});
         }
         try this.clear();
+        return size;
     }
 
     /// Clear the entire screen and reset the screen buffer, to force a re-draw with the next `flush` call.
@@ -88,7 +85,9 @@ pub const Buffered = struct {
 
     /// Write *virtual screen* to alternate screen (should be called once and last during each render loop iteration in the main loop).
     pub fn flush(this: *@This()) !void {
+        try terminal.hideCursor();
         // TODO measure timings of rendered frames?
+        var cursor_position: ?Point = null;
         const writer = terminal.writer();
         const s = this.screen;
         const vs = this.virtual_screen;
@@ -97,14 +96,36 @@ pub const Buffered = struct {
                 const idx = (row * this.size.x) + col;
                 const cs = s[idx];
                 const cvs = vs[idx];
+
+                // update the latest found cursor position
+                if (cvs.style.cursor) {
+                    assert(cursor_position == null);
+                    cursor_position = .{
+                        .x = @truncate(col),
+                        .y = @truncate(row),
+                    };
+                }
+
                 if (cs.eql(cvs)) continue;
 
                 // render differences found in virtual screen
-                try terminal.setCursorPosition(.{ .y = @truncate(row + 1), .x = @truncate(col + 1) });
+                try terminal.setCursorPosition(.{ .y = @truncate(row), .x = @truncate(col) });
                 try cvs.value(writer);
                 // update screen to be the virtual screen for the next frame
                 s[idx] = vs[idx];
             }
         }
+        if (cursor_position) |point| {
+            try terminal.showCursor();
+            try terminal.setCursorPosition(point);
+        }
     }
 };
+
+const std = @import("std");
+const meta = std.meta;
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const terminal = @import("terminal.zig");
+const Cell = @import("cell.zig");
+const Point = @import("point.zig").Point;

src/root.zig

@@ -17,7 +17,6 @@ pub const Renderer = @import("render.zig");
 // Container Configurations
 pub const Border = container.Border;
 pub const Rectangle = container.Rectangle;
-pub const Scroll = container.Scroll;
 pub const Layout = container.Layout;
 
 pub const Cell = @import("cell.zig");

src/style.zig

@@ -7,11 +7,13 @@
 
 // taken from https://github.com/rockorager/libvaxis/blob/main/src/Cell.zig (MIT-License)
 // with slight modifications
-const std = @import("std");
 
-const Color = @import("color.zig").Color;
+fg: Color = .default,
-
+bg: Color = .default,
-pub const Style = @This();
+ul: Color = .default,
+cursor: bool = false,
+ul_style: Underline = .off,
+emphasis: []const Emphasis,
 
 pub const Underline = enum {
     off,
@@ -34,41 +36,43 @@ pub const Emphasis = enum(u8) {
     strikethrough,
 };
 
-fg: Color = .default,
-bg: Color = .default,
-ul: Color = .default,
-ul_style: Underline = .off,
-emphasis: []const Emphasis,
-
 pub fn eql(this: Style, other: Style) bool {
-    return std.meta.eql(this, other);
+    return meta.eql(this, other);
 }
 
 // TODO might be useful to use the std.ascii stuff!
 
 pub fn value(this: Style, writer: anytype, cp: u21) !void {
     var buffer: [4]u8 = undefined;
-    const bytes = try std.unicode.utf8Encode(cp, &buffer);
+    const bytes = try unicode.utf8Encode(cp, &buffer);
-    std.debug.assert(bytes > 0);
+    assert(bytes > 0);
     // build ansi sequence for 256 colors ...
     // foreground
-    try std.fmt.format(writer, "\x1b[", .{});
+    try format(writer, "\x1b[", .{});
     try this.fg.write(writer, .fg);
     // background
-    try std.fmt.format(writer, ";", .{});
+    try format(writer, ";", .{});
     try this.bg.write(writer, .bg);
     // underline
     // FIX assert that if the underline property is set that the ul style and the attribute for underlining is available
-    try std.fmt.format(writer, ";", .{});
+    try format(writer, ";", .{});
     try this.ul.write(writer, .ul);
     // append styles (aka attributes like bold, italic, strikethrough, etc.)
-    for (this.emphasis) |attribute| try std.fmt.format(writer, ";{d}", .{@intFromEnum(attribute)});
+    for (this.emphasis) |attribute| try format(writer, ";{d}", .{@intFromEnum(attribute)});
-    try std.fmt.format(writer, "m", .{});
+    try format(writer, "m", .{});
     // content
-    try std.fmt.format(writer, "{s}", .{buffer[0..bytes]});
+    try format(writer, "{s}", .{buffer[0..bytes]});
-    try std.fmt.format(writer, "\x1b[0m", .{});
+    try format(writer, "\x1b[0m", .{});
 }
 
 // TODO implement helper functions for terminal capabilities:
 // - links / url display (osc 8)
 // - show / hide cursor?
+
+const std = @import("std");
+const unicode = std.unicode;
+const meta = std.meta;
+const assert = std.debug.assert;
+const format = std.fmt.format;
+const Color = @import("color.zig").Color;
+const Style = @This();

src/terminal.zig

@@ -1,15 +1,3 @@
-const std = @import("std");
-const code_point = @import("code_point");
-const ctlseqs = @import("ctlseqs.zig");
-const input = @import("input.zig");
-
-const Key = input.Key;
-const Point = @import("point.zig").Point;
-const Size = @import("point.zig").Point;
-const Cell = @import("cell.zig");
-
-const log = std.log.scoped(.terminal);
-
 // Ref: https://vt100.net/docs/vt510-rm/DECRPM.html
 pub const ReportMode = enum {
     not_recognized,
@@ -21,62 +9,62 @@ pub const ReportMode = enum {
 
 /// Gets number of rows and columns in the terminal
 pub fn getTerminalSize() Size {
-    var ws: std.posix.winsize = undefined;
+    var ws: posix.winsize = undefined;
-    _ = std.posix.system.ioctl(std.posix.STDIN_FILENO, std.posix.T.IOCGWINSZ, @intFromPtr(&ws));
+    _ = posix.system.ioctl(posix.STDIN_FILENO, posix.T.IOCGWINSZ, @intFromPtr(&ws));
     return .{ .x = ws.col, .y = ws.row };
 }
 
 pub fn saveScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.save_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.save_screen);
 }
 
 pub fn restoreScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.restore_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.restore_screen);
 }
 
 pub fn enterAltScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.smcup);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.smcup);
 }
 
 pub fn exitAltScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.rmcup);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.rmcup);
 }
 
 pub fn clearScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.clear_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.clear_screen);
 }
 
 pub fn hideCursor() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.hide_cursor);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.hide_cursor);
 }
 
 pub fn showCursor() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.show_cursor);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.show_cursor);
 }
 
 pub fn setCursorPositionHome() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.home);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.home);
 }
 
 pub fn enableMouseSupport() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.mouse_set);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.mouse_set);
 }
 
 pub fn disableMouseSupport() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.mouse_reset);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.mouse_reset);
 }
 
 pub fn read(buf: []u8) !usize {
-    return try std.posix.read(std.posix.STDIN_FILENO, buf);
+    return try posix.read(posix.STDIN_FILENO, buf);
 }
 
 pub fn write(buf: []const u8) !usize {
-    return try std.posix.write(std.posix.STDIN_FILENO, buf);
+    return try posix.write(posix.STDIN_FILENO, buf);
 }
 
 fn contextWrite(context: @This(), data: []const u8) anyerror!usize {
     _ = context;
-    return try std.posix.write(std.posix.STDOUT_FILENO, data);
+    return try posix.write(posix.STDOUT_FILENO, data);
 }
 
 const Writer = std.io.Writer(
@@ -91,19 +79,19 @@ pub fn writer() Writer {
 
 pub fn setCursorPosition(pos: Point) !void {
     var buf: [64]u8 = undefined;
-    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.y, pos.x });
+    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.y + 1, pos.x + 1 });
-    _ = try std.posix.write(std.posix.STDIN_FILENO, value);
+    _ = try posix.write(posix.STDIN_FILENO, value);
 }
 
 pub fn getCursorPosition() !Size.Position {
     // Needs Raw mode (no wait for \n) to work properly cause
     // control sequence will not be written without it.
-    _ = try std.posix.write(std.posix.STDIN_FILENO, "\x1b[6n");
+    _ = try posix.write(posix.STDIN_FILENO, "\x1b[6n");
 
     var buf: [64]u8 = undefined;
 
     // format: \x1b, "[", R1,..., Rn, ";", C1, ..., Cn, "R"
-    const len = try std.posix.read(std.posix.STDIN_FILENO, &buf);
+    const len = try posix.read(posix.STDIN_FILENO, &buf);
 
     if (!isCursorPosition(buf[0..len])) {
         return error.InvalidValueReturned;
@@ -166,8 +154,8 @@ pub fn isCursorPosition(buf: []u8) bool {
 ///
 /// `bak`: pointer to store termios struct backup before
 /// altering, this is used to disable raw mode.
-pub fn enableRawMode(bak: *std.posix.termios) !void {
+pub fn enableRawMode(bak: *posix.termios) !void {
-    var termios = try std.posix.tcgetattr(std.posix.STDIN_FILENO);
+    var termios = try posix.tcgetattr(posix.STDIN_FILENO);
     bak.* = termios;
 
     // termios flags used by termios(3)
@@ -192,20 +180,20 @@ pub fn enableRawMode(bak: *std.posix.termios) !void {
     termios.cflag.CSIZE = .CS8;
     termios.cflag.PARENB = false;
 
-    termios.cc[@intFromEnum(std.posix.V.MIN)] = 1;
+    termios.cc[@intFromEnum(posix.V.MIN)] = 1;
-    termios.cc[@intFromEnum(std.posix.V.TIME)] = 0;
+    termios.cc[@intFromEnum(posix.V.TIME)] = 0;
 
-    try std.posix.tcsetattr(
+    try posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+        posix.STDIN_FILENO,
         .FLUSH,
         termios,
     );
 }
 
 /// Reverts `enableRawMode` to restore initial functionality.
-pub fn disableRawMode(bak: *std.posix.termios) !void {
+pub fn disableRawMode(bak: *posix.termios) !void {
-    try std.posix.tcsetattr(
+    try posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+        posix.STDIN_FILENO,
         .FLUSH,
         bak.*,
     );
@@ -215,13 +203,13 @@ pub fn disableRawMode(bak: *std.posix.termios) !void {
 pub fn canSynchornizeOutput() !bool {
     // Needs Raw mode (no wait for \n) to work properly cause
     // control sequence will not be written without it.
-    _ = try std.posix.write(std.posix.STDIN_FILENO, "\x1b[?2026$p");
+    _ = try posix.write(posix.STDIN_FILENO, "\x1b[?2026$p");
 
     var buf: [64]u8 = undefined;
 
     // format: \x1b, "[", "?", "2", "0", "2", "6", ";", n, "$", "y"
-    const len = try std.posix.read(std.posix.STDIN_FILENO, &buf);
+    const len = try posix.read(posix.STDIN_FILENO, &buf);
-    if (!std.mem.eql(u8, buf[0..len], "\x1b[?2026;") or len < 9) {
+    if (!mem.eql(u8, buf[0..len], "\x1b[?2026;") or len < 9) {
         return false;
     }
 
@@ -238,3 +226,16 @@ fn getReportMode(ps: u8) ReportMode {
         else => ReportMode.not_recognized,
     };
 }
+
+const log = std.log.scoped(.terminal);
+
+const std = @import("std");
+const mem = std.mem;
+const posix = std.posix;
+const code_point = @import("code_point");
+const ctlseqs = @import("ctlseqs.zig");
+const input = @import("input.zig");
+const Key = input.Key;
+const Point = @import("point.zig").Point;
+const Size = @import("point.zig").Point;
+const Cell = @import("cell.zig");

src/testing.zig

@@ -1,23 +1,12 @@
 //! Testing namespace for `zterm` to provide testing capabilities for `Containers`, `Event` handling, `App`s and `Element` implementations.
-const std = @import("std");
-const event = @import("event.zig");
-const Container = @import("container.zig").Container;
-
-const Cell = @import("cell.zig");
-const DisplayWidth = @import("DisplayWidth");
-const Point = @import("point.zig").Point;
-
-// TODO how would I describe the expected screens?
-// - including styling?
-// - compare generated strings instead? -> how would this be generated for the user?
 
 /// Single-buffer test rendering pipeline for testing purposes.
 pub const Renderer = struct {
-    allocator: std.mem.Allocator,
+    allocator: Allocator,
     size: Point,
     screen: []Cell,
 
-    pub fn init(allocator: std.mem.Allocator, size: Point) @This() {
+    pub fn init(allocator: Allocator, size: Point) @This() {
         const screen = allocator.alloc(Cell, @as(usize, size.x) * @as(usize, size.y)) catch @panic("testing.zig: Out of memory.");
         @memset(screen, .{});
 
@@ -116,11 +105,10 @@ pub const Renderer = struct {
 /// }, &container, @import("test/container/border.all.zon"));
 /// ```
 pub fn expectContainerScreen(size: Point, container: *Container(event.SystemEvent), expected: []const Cell) !void {
-    const allocator = std.testing.allocator;
+    const allocator = testing.allocator;
     var renderer: Renderer = .init(allocator, size);
     defer renderer.deinit();
 
-    try renderer.resize(size);
     container.resize(size);
     container.reposition(.{});
     try renderer.render(Container(event.SystemEvent), container);
@@ -133,10 +121,10 @@ pub fn expectContainerScreen(size: Point, container: *Container(event.SystemEven
 /// the contents of a given screen from the `zterm.testing.Renderer`. See
 /// `zterm.testing.expectContainerScreen` for an example usage.
 pub fn expectEqualCells(origin: Point, size: Point, expected: []const Cell, actual: []const Cell) !void {
-    const allocator = std.testing.allocator;
+    const allocator = testing.allocator;
 
-    try std.testing.expectEqual(expected.len, actual.len);
+    try testing.expectEqual(expected.len, actual.len);
-    try std.testing.expectEqual(expected.len, @as(usize, size.y) * @as(usize, size.x));
+    try testing.expectEqual(expected.len, @as(usize, size.y) * @as(usize, size.x));
 
     var expected_cps = try std.ArrayList(Cell).initCapacity(allocator, size.x);
     defer expected_cps.deinit();
@@ -192,10 +180,20 @@ pub fn expectEqualCells(origin: Point, size: Point, expected: []const Cell, actu
     // test failed
     try buffer.flush();
 
-    std.debug.lockStdErr();
+    debug.lockStdErr();
-    defer std.debug.unlockStdErr();
+    defer debug.unlockStdErr();
 
     const std_writer = std.io.getStdErr().writer();
     try std_writer.writeAll(output.items);
     return error.TestExpectEqualCells;
 }
+
+const std = @import("std");
+const debug = std.debug;
+const testing = std.testing;
+const Allocator = std.mem.Allocator;
+const event = @import("event.zig");
+const Container = @import("container.zig").Container;
+const Cell = @import("cell.zig");
+const DisplayWidth = @import("DisplayWidth");
+const Point = @import("point.zig").Point;